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FOREWORD 


This  technical  report  covers  work  performed  under  Air  Force 
Contract  F33600-87-C-04 64 ,  DAPro  Project.  This  contract  is 
sponsored  by  the  Manufacturing  Technology  Directorate,  Air  Force 
Systems  Command,  Wright-Patterson  Air  Force  Base,  Ohio.  It  was 
administered  under  the  technical  direction  of  Mr.  Bruce  A. 
Rasmussen,  Branch  Chief,  Integration  Technology  Division, 
Manufacturing  Technology  Directorate,  through  Mr.  David  L.  Judson, 
Project  Manager.  The  Prime  Contractor  was  Integration  Technology 
Services,  Software  Programs  Division,  of  the  Control  Data 
Corporation,  Dayton,  Ohio,  under  the  direction  of  Mr.  W.  A. 
Osborne.  The  DAPro  Project  Manager  for  Control  Data  Corporation 
was  Mr.  Jimmy  P.  Maxwell. 


The  DAPro  project  was  created  to  continue  the  development,  test, 
and  demonstration  of  the  Integrated  Information  Support  System 
(IISS) .  The  IISS  technology  work  comprises  enhancements  to  IISS 
software  and  the  establishment  and  operation  of  IISS  test  bed 
hardware  and  communications  for  developers  and  users. 

The  following  list  names  the  Control  Data  Corporation 
subcontractors  and  their  contributing  activities: 


SUBCONTRACTOR 


ROLE 


Control  Data  Corporation 


D.  Appleton  Company 


ONTEK 


Simpact  Corporation 


Structural  Dynamics 
Research  Corporation 


Arizona  State  University 


Responsible  for  the  overall  Common 
Data  Model  design  development  and 
implementation,  IISS  integration  and 
test,  and  technology  transfer  of  IISS. 

Responsible  for  providing  software 
information  services  for  the  Common 
Data  Model  and  IDEF1X  integration 
methodology . 

Responsible  for  defining  and  testing  a 
representative  integrated  system  base 
in  Artificial  Intelligence  techniques 
to  establish  fitness  for  use. 

Responsible  for  Communication 
development . 

Responsible  for  User  Interfaces, 
Virtual  Terminal  Inter face , and  Network 
Transaction  Manager  design, 
development,  implementation,  and 
support . 

Responsible  for  test  bed  operations 
and  support . 
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SECTION  1 
INTRODUCTION 


This  manual  describes  the  Form  Processor  (FP)  which  is  a  set 
of  callable  execution  time  routines  available  to  an  application 
program  for  form  processing.  The  information  is  addressed  to 
application  programmers  using  the  Integrated  Information  Support 
System  ( IISS)  .  T 

‘The  FP  routines  allow  programs  and  their  users  to  communicate 
through  pre-defined  forms  on  a  terminal.  The  forms  can  be  defined 
at  run-time  using  FP  routines  or  by  using  the  Form  Editor.  When 
the  application  runs,  the  FP  handles: 

o  ]  1  Retrieval  of  a  pre-defined  form 
O  2 }  Display  of  the  form 

o  J  Filling  out  of  the  form  (from  the  user  point  of  view)' 
o  «  Data  integrity  checkingj 
6  ■T  Providing  a  help  facility j 
0  „ Def  init ion  of  new  forms  at  run-time;  ‘  *  > 

_ .g  Modification  of  existing  forms  at  run-time,.  - 

The  application  program  can  be  'written  in  most  of  the  high 
level  programming  languages.  However,  since  the  form  data  are 
highly  structured,  it  is  w;se  to  choose  a  language  that  supports 
data  structures  such  as  PL1 ,  COBOL,  or  C. 


All  FP  calls  refer  to  specific  forms  and  data  within  forms  by 
names  that  are  assigned  during  form  definition.  A  typical  order 
of  events  in  an  application  program  using  these  routines  is: 


1.  Initialize  Form  Processor. 

2.  Open  forms. 

3.  Add  forms  to  windows. 

4.  Put  data  in  forms. 

5.  Put  data  in  message  line. 

6.  Send  screen  to  terminal  and  get  input  from  the  user. 

7.  Read  data  from  forms. 


When  processing  has  finished,  close  forms  and  go  to  =10. 

8.  Remove  pages  that  will  not  be  displayed  or  replaced. 

9.  Replace  forms  if  necessary. 


To  continue  processing,  return  to  =3. 


10.  Terminate  Form  Processor. 


The  concepts  of  form  processing  as  well  as  terms  such  as 
windows  and  pages  are  explained  in  Section  1  of  this  manual. 
Details  of  the  callabLe  FP  routines  are  given  in  Section  4. 
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SECTION  2 
DOCUMENTS 


2 . 1  Reference  Documents 

[1]  Structural  Dynamics  Research  Corporation,  IISS  Form  Processor 

Development  Specification,  DS  620244200A,  16  February  1987. 

[2]  Systran,  ICAM  Documentat ion  Standards,  IDS150120000C,  15 
September  1983. 

This  manual  is  one  of  a  set  of  user's  manuals  that  together 
describe  how  to  operate  in  the  IISS  environment.  The 
complete  set  consists  of  the  following  manuals  listed  here 
for  reference: 

[1]  Structural  Dynamics  Research  Corporation,  IISS  Form  Editor 

User's  Manual,  UM  620244400A,  16  February  1987. 

Explains  how  to  define  and  maintain  electronic  forms.  This 
manual  is  intended  for  use  by  programmers  writing  application 
programs  that  use  the  Form  Processor. 

[2]  Structural  Dynamics  Research  Corporation,  IISS  Form  Processor 

User's  Manual,  UM  620244200A,  16  February  1987. 

Describes  the  set  of  callable,  execution-time  routines 
available  to  an  application  program  for  the  processing  of 
electronic  forms.  This  manual  is  intended  for  use  by 
programmers  writing  application  programs  for  the  IISS 
environment . 

[3]  Structural  Dynamics  Research  Corporation,  IISS  Terminal 

Operator  Guide,  0M  620244000A,  16  February  1987 . 

Explains  how  to  operate  the  generic  IISS  terminal  when 
running  an  IISS  application  program.  The  IISS  end  user 
environment,  function  selection,  and  some  pre-defined 
applications  are  also  described. 

[4]  Structural  Dynamics  Research  Corporation,  IISS  Text  Editor 

User ' s  Manual ,  UM  620244600A,  16  February  1987. 

Explains  the  use  of  file  editing  functions  including: 
insert,  delete,  move,  and  replace  text. 

[5]  Structural  Dynamics  Research  Corporation,  IISS  Rapid 

Application  Generator  User's  Manual,  UM  62C244502A,  16 

February  1987. 

Describes  the  Application  Definition  Language  (ADL)  subset  ol 
Form  Definition  Language  ( FDL) ,  and  outlines  the  process  used 
for  translating  textual  definitions  of  interactive  database 
applications  into  programs  that  access  selected  data  base 
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information  resident  in  the  Common  Data  Model  (CDM) .  This 
information  is  accessible  through  the  IISS  Neutral  Data 
Manipulation  Language  (NDML) . 

[6]  Structural  Dynamics  Research  Corporation,  IISS  Report  Writer 

User 1 s  Manual ,  UM  620244501A,  16  February  1987. 

Describes  the  Report  Definition  Language  ( RDL)  subset  of  Form 
Definition  Language  ( FDL) ,  and  outlines  the  process  of 
creating  a  hard  copy  report  of  selected  data  base  information 
resident  in  the  Common  Data  Model  (CDM) .  This  information  is 
accessible  through  the  IISS  Neutral  Data  Manipulation 
Language  (NDML) . 

[7]  Structural  Dynamics  Research  Corporation,  IISS  Virtual 
Terminal  User's  Manual,  UM  620244300A,  16  February  1987. 

Explains  the  program  callable  interface  to  the  IISS  Virtual 
Terminal.  The  callable  routines,  Virtual  Terminal  commands, 
and  the  implementation  of  additional  terminals  are  described. 
This  manual  is  intended  for  use  by  application  and  system 
programmers  working  in  the  IISS  environment. 

2 . 2  Terms  and  Abbreviations 

American  Standard  Code  for  Information  Interchange  (ASCII) : 
The  character  set  defined  by  ANSI  X3 . 4  and  used  by  most  computer 
vendors. 

Application  Interface  (AI) :  A  subset  of  the  IISS  User 
Interface  that  consists  of  the  callable  routines  that  are  linked 
with  applications  that  use  the  Form  Processor  or  Virtual  Terminal. 
The  AI  enables  applications  to  be  hosted  on  computers  other  than 
the  host  of  the  User  Interface. 

Application  Process  (AP) ;  A  cohesive  unit  of  software  that 
can  be  initiated  as  a  unit  to  perform  some  function  or  functions. 

Attribute :  A  field  characteristic  such  blinking, 

highlighted,  black,  etc.  and  various  other  combinations. 

Background  attributes  are  defined  for  forms  or  windows  only. 
Foreground  attributes  are  defined  for  items.  Attributes  may  be 
permanent,  i.e.,  they  remain  the  same  unless  changed  by  the 
application  program,  or  they  may  be  temporary,  i.e.,  they  remain 
in  effect  until  the  window  is  redisplayed. 

Child  Structure:  A  structure  that  is  referenced  from  within 
another  structure  (the  "parent  structure")  via  an  Execute 
Structure  Element. 

Common  Data  Model  (CDM):  The  IISS  subsystem  that  describes 
common  data  application  process  formats,  form  definitions,  etc.  of 
the  IISS  and  includes  conceptual  schema,  external  schemas, 
internal  schemas,  and  schema  transformation  operators. 
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Computer  Program  Conf iquration  Item  (CPCI):  An  aggregation 
of  computer  programs  or  any  of  their  discrete  portions,  which 
satisfies  an  end-use  function. 

Conceptual  Schema  (CS):  The  standard  definition  used  for  all 
data  m  the  COM.  It  is  based  on  IDEF1  information  modeling. 

Current  Cursor  Position:  The  position  of  the  cursor  before 
an  edit  command  or  function  is  issued  in  the  text  editor. 

Cursor  Position:  The  position  of  the  cursor  after  any 
command  is  issued. 

Device  Drivers  (DP):  Software  modules  written  to  handle  I/O 
for  a  specific  kind  of  terminal.  The  modules  map  terminal 
specific  commands  and  data  to  a  neutral  format.  Device  Drivers 
are  part  of  the  UI  Virtual  Terminal. 

Display  List :  A  list  of  all  the  open  forms  that  are 
currently  being  processed  by  the  FP  or  the  user. 

Display  Size:  The  number  of  lines  used  in  the  edit  area. 

Execute  Structure  Element:  An  instruction  within  a  structure 
(the  "parent"  structure)  which  points  to  another  structure  (the 
"child"  structure).  During  traversal  of  the  parent  structure, 
when  an  execute  structure  element  is  encountered,  traversal  of  the 
parent  structure  is  stopped  and  the  child  structure  is  traversed. 
When  traversal  of  the  child  structure  has  completed,  traversal  of 
the  parent  structure  resumes  at  the  point  where  the  execute 
structure  element  was  encountered. 

Extended  Binary  Coded  Decimal  Interchange  Code  (EBCDIC) :  The 
character  set  used  by  a  few  computer  vendors  (notably  IBM)  instead 
of  ASCII. 

External  Schema  (ES) :  An  application's  view  of  the  CDM ' s 
conceptual  schema. 

Field :  Two  dimensional  space  on  a  terminal  screen. 

Field  Pointer:  Indicates  the  ITEM  which  contains  the  current 
cursor  position. 

Form:  Structured  view  which  may  be  imposed  on  windows  or 

other  forms.  A  form  is  composed  of  fields.  These  fields  may  be 
defined  as  forms,  items,  and  windows. 

Form  Definition  (FD):  Form  Definition  Language  after 
compilation.  It  is  read  at  run-time  by  the  Form  Processor. 

Form  Definition  Language  (FPL):  The  language  in  which 
electronic  forms  are  defined. 

Form  Driven  Form  Editor  (FDFE):  The  subset  of  the  Form  Edits: 
which  consists  of  a  form  driven  application  used  to  create  Form 
Definition  files  interactively. 
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Form  Editor  (FE) :  A  subset  of  the  IISS  User  Interface  that 
is  used  to  create  definitions  of  forms.  ^he  FE  consists  of  the 
Form  Driven  Form  Editor  and  the  Form  Language  Compiler. 

Form  Hierarchy:  A  graphic  representation  of  the  way  in  which 
forms,  items  and  windows  are  related  to  their  parent  form. 

Form  Language  Compiler  (FLAN) :  A  subset  of  the  Form  Editor 
which  translates  Form  Definition  Language  statements  into  form 
Definition  files. 

Form  Processor  (FP) :  A  subset  of  the  IISS  User  Interface 
that  consists  of  a  set  of  callable,  execution-time  routines 
available  to  an  application  program  for  form  processing. 

Form  Processor  Text  Editor  ( FPTE) :  A  subset  of  the  Form 
Processor  that  consists  of  software  modules  that  provide  text 
editing  capabilities  to  all  users  of  applications  that  use  the 
Form  Processor. 

Integrated  Information  Support  System  (IISS):  A  test 
computing  environment  used  to  investigate,  demonstrate  and  test 
the  concepts  of  information  management  and  information  integration 
in  the  context  of  Aerospace  Manufacturing.  The  IISS  addresses  the 
problems  of  integration  of  data  resident  on  heterogeneous  data 
bases  supported  by  heterogeneous  computers  interconnected  via  a 
Local  Area  Network. 

Item:  A  non-decomposab’  a  area  of  a  form  into  which 

hard-coded  descriptive  text  rr  ay  be  placed.  An  item  is  the  only 
defined  area  where  user  data  may  be  input/output. 

Logical  Device:  A  conceptual  device  that  identifies  a  top 
level  window  of  an  application.  It  is  used  to  distinguish  between 
multiple  applications  running  simultaneously  on  a  physical  device. 
NOTE  that  a  single  application  can  have  more  than  one  logical 
device.  To  the  end  user  this  also  appears  as  multiple 
applications  running  simultaneously. 

Message :  Descriptive  text  which  may  be  returned  in  the 

standard  message  line  on  the  terminal  screen.  They  are  used  to 
warn  of  errors  or  provide  other  user  information. 

Message  Line:  A  line  on  the  terminal  screen  that  is  used  to 
display  messages. 

Network  Transaction  Manager  ( NTM ) :  The  IISS  subsystem  that 
performs  the  coordination,  communication  and  housekeeping 
functions  required  to  integrate  the  Application  Processes  and 
System  Services  resident  on  the  various  hosts  into  a  cohesive 
system. 

Open  List:  A  list  of  all  the  forms  that  are  currently  open 
for  an  application  process. 
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Operating  System  (OS) :  Software  supplied  with  a  computer 
which  allows  it  to  supervise  its  own  operations  and  manage  access 
to  hardware  facilities  such  as  memory  and  peripherals. 

Page :  An  instance  of  a  form  in  a  window  that  is  created 

whenever  a  form  is  added  to  a  window. 

Paging  and  Scrolling:  A  method  which  allows  a  form  to 
contain  more  data  than  can  be  displayed  with  provisions  for 
viewing  any  portion  of  the  data  buffer. 

Parent  Structure:  A  structure  which  references  another 
structure  (the  "child"  structure)  via  an  Execute  Structure 
Element . 

Physical  Device:  A  hardware  terminal. 

Presentation  Schema  (PS):  May  be  equivalent  to  a  form.  It 
is  the  view  presented  to  the  user  of  the  application. 

Previous  Cursor  Position:  The  position  of  the  cursor  when 
the  previous  edit  command  was  issued. 

Qualified  Name:  The  name  of  a  form,  item  or  window  preceded 
by  the  hierarchy  path  so  that  it  is  uniquely  identified. 

State  List:  A  list  of  conditions  which  are  in  effect  for  the 
currently  open  structure,  e.g.,  current  polyline  attributes  are 
the  color  blue,  line  width  1,  lir  ype  solid,  open  workstation  is 
number  1.  These  attributes  st.  y  in.  effect  until  another  structure 
is  opened  which  changes  t’.  a  state  list. 

Structure :  A  list  of  instructions  that,  when  executed,  will 

product  a  graphics  pictu'-~ 

Structure  Element:  One  of  the  instructions  in  the  structure 
which  is  used  to  create  a  graphics  picture. 

Subform:  A  form  that  is  used  within  another  form. 

Transformation :  The  process  of  changing  the  size  and/or 

orientation  of  a  displayed  graphics  picture.  The  transformations 
are  made  via  the  use  of  coordinate  geometry,  trigonometry,  and 
matrix  mathematics. 

Traversal :  The  process  of  executing  the  list  of  instructions, 

in  a  structure  in  order  to  create  a  graphics  picture. 

User  Data:  Data  which  is  either  input  by  the  user  or  output 
by  the  application  programs  to  items. 

User  Interface  {UI) :  The  IISS  subsystem  that  controls  the 
user's  terminal  and  interfaces  with  the  rest  of  the  system.  The 
U I  consists  of  two  major  subsystems:  the  User  Interface 
Development  System  (UIDS)  and  the  User  Interface  Management  Syster 
(UIMS )  . 
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User  Interface  Development  System  (UIDS) :  The  collection  of 
IISS  User  Interface  subsystems  that  are  used  by  applications 
programmers  as  they  develop  IISS  appl ications .  The  UIDS  includes 
the  Form  Editor  and  the  Application  Generator. 

User  Interface  Management  System  (UIMS) :  The  run-time  UI. 

The  UIMS  consists  of  the  Form  Processor,  Virtual  Terminal, 
Application  Interface,  the  User  Interface  Services  and  the  Text 
Editor. 

User  Interface  Monitor  (UIM) :  The  part  of  the  Form  Processor 
that  handles  messaging  between  the  NTM  and  the  UI.  The  UIM  also 
provides  authorization  checks  and  initiates  applications. 

User  Interface/Virtual  Terminal  Interface  (UI/VTI):  Another 
name  for  the  User  Interface .  . *  . 

Virtual  Terminal  (VT) :  A  subset  of  the  IISS  User  Interface 
that  performs  the  interfacing  between  different  terminals  and  the 
UI.  This  is  done  by  defining  a  specific  set  of  terminal  features 
and  protocols  which  must  be  supported  by  the  UI  software  which 
constitutes  the  virtual  terminal  definition.  Specific  terminals 
are  then  mapped  against  the  virtual  terminal  software  by  specific 
software  modules  written  for  each  type  of  real  terminal  supported. 

Virtual  Terminal  Interface  (VTI) :  The  callable  interface  to 
the  VT. 

Window:  A  Dynamic  area  of  a  terminal  screen  on  which 

pre-defined  forms  may  be  placed  at  run-time. 

Window  Manager:  The  facility  which  allows  the  following  to 
be  manipulated:  size  and  location  of  windows,  the  device  on  which 
an  application  is  running,  and  the  position  of  a  form  within  a 
window.  The  Window  Manager  is  part  of  the  Form  Processor. 
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FORM  PROCESSING  CONCEPTS 


This  section  explains  several  FP  implementation  concepts  that 
will  enable  you  to  use  the  callable  routines  effectively. 

3 . 1  Displaying  Forms 

The  terminal  screen  can  be  thought  of  as  a  window  in  which 
forms  are  displayed.  To  determine  what  the  user  of  your 
application  will  see  in  this  window,  your  application  must  build  a 
Display  List.  As  explained  in  the  Form  Editor  User's  Manual,  a 
form  is  composed  of  fields  which  can  be  defined  as  subforms, 
items,  graphs,  graphics  primitives,  and  windows.  Since  windows 
can  contain  forms,  which  in  turn  can  contain  forms,  items,  graphs, 
graphics  primitives  (polylines,  polymarkers,  fill  areas,  and 
graphics  text),  and  windows,  the  Display  List  can  be  a  form 
hierarchy  like  that  shown  in  Figure  3-1. 
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Figure  3-1  Display  List  Hierarchy 
3 . 2  Building  the  Display  List 

The  Display  List  must  be  built  from  the  top  down.  At  the  top 
of  the  Display  List  will  always  be  the  form  PSCREN,  which  is  added 
to  the  Display  List  as  part  of  initialization.  PSCREN  contains 
the  window  SCREEN  which  is  where  top-level  user  forms  are  placed. 
The  include  file  FPPARM  defines  SCREN  which  refers  to  this  window. 
A  form  cannot  be  added  to  a  window  unless  that  window  is  already 


3-1 


UM  620344200 
30  September  1990 


on  the  Display  List.  The  Display  List  is  formed  as  the 
application  dynamically  adds,  removes,  and  replaces  forms  in 
windows  using  the  routines  ADDFRM,  RPLFRM,  and  RMVPAG. 

3 . 3  Opening  Forms 


In  order  to  be  put  on  the  Display  List  or  to  be  modified  at 
run-time,  a  form  must  be  brought  into  memory,  or  "opened".  This 
is  done  either  explicitly  when  OPNFRM  is  called,  or  implicitly 
when  ADDFRM  is  called  to  actually  add  the  form  to  the  Display 
List.  There  are  several  factors  to  consider  when  deciding  which 
type  of  open  is  more  appropriate  for  each  situation. 


When 

following 

o 

o 

o 

o 

o 


the  application  explicitly  opens  all  forms,  the 
will  be  true: 

Startup  is  slow 

All  necessary  forms  are  available 
Missing  form  errors  are  avoided 
Response  time  is  consistent 

Resources  may  be  wasted  opening  and  closing  forms  that 
are  not  used 


When  the  application  implicitly  opens  forms,  the  following 
conditions  are  true: 


o  Startup  is  fast 

o  Missing  form  errors  can  occur 

o  Response  time  is  inconsistent  -  first  access  takes 

longer  since  the  form  must  be  opened 
o  Resources  are  not  wasted 

3 . 4  Identifying  Window  Contents 

As  the  application  builds  the  Display  List,  forms  may  become 
layered  in  a  window,  i.e.,  they  become  stacked  on  top  of  each 
other,  like  pages  in  a  book.  Page  one  may  obscure  page  two  from 
sight,  but  page  two  becomes  visible  when  page  one  is  moved  out  of 
the  way.  Within  the  Form  Processor,  a  page  is  an  instance  of  a 
form  in  a  window.  Adding  a  form  to  a  window  causes  a  page  to  be 
created.  Removing  a  form  from  the  window  deletes  a  page.  The 
form  on  any  given  page  may  also  be  replaced  by  a  different  form. 

The  following  figures  illustrate  how  pages  are  created  as 
forms  are  added,  removed,  and  replaced  in  a  window.  The  upper 
left  hand  corners  of  the  boxes  contain  the  form  name.  The  upper 
right  hand  corners  contain  the  page  number. 

In  the  first  example,  FORM1  has  been  added  to  the  window 
using  ADDFRM,  creating  page  1.  Next,  page  2  has  been  created  by 
calling  ADDFRM  to  add  FORM2  to  the  window. 
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Figure  3-2  After  Two  ADDFRM  Calls 

In  Figure  3-3,  page  2  has  been  altered  by  replacing  FORM2 
with  FORM3  using  RPLFRM. 
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Figure  3-3  After  RPLFRM 

In  Figure  3-4,  RMVPAG  has  been  used  to  remove  page  2  from  the 
window  so  that  only  page  1  remains. 
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Figure  3-4  After  RMVPAG 

These  calls  are  used  to  build  the  Display  List.  To  display 
the  objects  on  the  Display  List  on  the  terminal,  the  routines 
OUTSCR  or  OISCR  must  be  called. 

3 . 5  Identifying  Data  on  the  Display  List 

As  illustrated  in  Figure  3-1,  it  is  possible  to  have  a  form 
that  is  used  in  more  than  one  window  or  as  a  subform  of  more  than 
one  form.  When  forms  are  used  in  this  manner,  it  is  necessary  to 
have  a  means  of  identifying  the  specific  Display  List  element  in 
which  to  place  data  or  from  which  to  retrieve  data.  A  similar 
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problem  exists  when  a  form  contains  arrays  (i.e.,  repeating 
occurrences  of  a  field).  To  solve  these  problems,  Display  List 
elements  are  identified  using  qualified  names. 

A  fully  qualified  name  specifies  all  forms,  windows,  and 
items  on  a  path  to  the  Display  List  element  being  identified  with 
page  numbers  specified  for  all  forms  within  windows  and  subscripts 
specified  for  all  array  elements.  If  a  qualified  name  begins  with 
a  dot  it  is  an  absolute  name  and  the  path  starts  at  the  top 

of  the  Display  List  (i.e.,  the  form  PSCREN) .  A  qualified  name 
which  does  not  begin  with  a  dot  is  a  relative  name  that  starts  at 
a  default  path  on  the  Display  List.  The  default  path  is  set 
according  to  the  most  recent  call  to  the  routine  SETDQN .  By  using 
relative  names  and  SETDQN,  a  procedure  can  be  written  which  uses  a 
form  without  any  knowledge  of  the  window(s)  in  which  the  form  is 
currently  displayed. 

To  identify  a  specific  Display  List  element,  its  qualified 
name  need  only  include  enough  elements  in  the  path  so  that  the 
path  is  unique.  A  qualified  name  has  the  general  form: 

namel.name2.  ...  namen; 

If  there  are  repeating  occurrences  of  a  field  in  the  path,  a 
specific  occurrence  following  the  field  name  may  optionally  be 
specified.  If  an  occurrence  is  not  specified,  all  of  the 
occurrences  are  searched  or  used  depending  upon  whether  the  array 
field  is  along  the  path  or  at  the  end  of  it.  If  the  path  includes 
a  window,  the  name  may  also  be  followed  by  an  optional  page 
number.  The  routines  GWINDO  and  GPAGE  are  used  to  find  out  the 
number  of  pages  in  a  window  and  the  name  of  the  form  on  a  specific 
page,  respectively.  If  the  page  number  is  not  specified,  the 
current  page  is  used.  The  entire  qualified  name  is  followed  with 
a  semicolon  (';•). 

The  Backus-Naur  specification  for  qualified  names  is: 

<qualified  narae>  ::  =  [.] <subname>  [ <subname_l ist> ]  ; 

<subname_l ist>  ::-  .<subname>  [ <subname_l ist> ] 

<sufcname>  ::=  <name>  [ ( <subscript_l ist > ) ]  [ "<M<page;>">" j 

<subscript_l ist>  ::=  <subscript#>  [ , <subscript_l ist> ] 

A  <name>  may  consist  of  up  to  ten  alphanumeric  and  underscore 
characters.  A  form  name  may  not  contain  underscores, 
however  and  specific  systems  may  further  restrict  the  length.  A 
<name>  must  begin  with  an  alphabetic  character  and  cannot  contain 
blanks.  For  example,  item_one,  field2,  and  ARRAY  are  all  valid 
names.  The  names  "7item",  "item  2",  and  "help_form"  are  all 
illegal  names. 

Entries  enclosed  in  square  brackets  ('[  ]')  are  optional. 
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Page  number  and  suoscript  number  may  be  absolute  or  relative 
as  explained  previously  in  this  section,  and  cannot  contain 
leading  spaces.  Leading  zeros  are  allowed.  For  example,  "1"  and 
"01"  both  refer  to  the  first  page  in  a  window. 

To  determine  if  a  qualified  name  is  legal,  the  following 
rules  are  applied: 

1.  The  qualified  name  specified  must  identify  a  path  in  the 
current  form  hierarchy  of  the  application.  To  identify  a  path, 
the  fields  in  the  name  must  exist,  and  they  must  be  in  the  correct 
hierarchical  order.  Fields  along  the  path  may  be  omitted  as  long 
as  the  fields  included  are  in  the  correct  order.  An  error  is 
returned  if  the  path  does  not  exist. 

2.  If  the  qualified  name  identifies  more  than  one  Display 
List  element,  the  field  is  chosen  whose  first  qualifier  occurs 
highest  in  the  hierarchy. 

3.  If  rule  2  does  not  resolve  the  conflict,  the  path  is 
chosen  which  spans  the  fewest  levels  in  the  hierarchy. 

4.  If  rule  3  does  not  resolve  the  conflict,  an  error  is 
returned . 


A 

I 

t 

B 


-t - H - + 


c 


D 


+ 


-  +  —  ■+■ 


E 


B 


C 


Level  1 
Level  2 

Level  3 

Level  4 
Level  5 


Figure  3-5  Form  Hierarchy 

Using  the  form  hierarchy  shown  in  Figure  3-5,  the  name  "D.C" 
could  refer  to  C  at  Level  3  or  Level  5.  When  Rule  2  is  applied, 
we  see  that  C  at  Level  3  would  be  used.  The  name  "A.C"  could  also 
be  used  to  identify  either  C.  When  Rule  3  is  applied,  we  again 
see  that  C  at  Level  3  would  be  used.  It  C  also  branched  from  L, 
there  would  be  two  C's  at  the  same  level.  Then,  it  the  path  name 
was  "D.C",  an  error  would  result.  To  access  the  C's  at  Level  5, 
you  would  have  to  specify  a  qualified  name  of  "D.B.C"  or  "D.E.C". 


In  Figure  3-6,  the  window  SCREEN  on  form  PSCREN  contains  the 
form  FORM1.  FORM1  contains  two  windows,  WINDGW1  and  WIND0W2,  and 
seven  items,  II,  12,  13,  and  four  occurrences  of  14.  Both  WINDOW! 

and  WINDOW 2  contain  FORM 2  which  contains  items  II  and  12. 
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Figure  3-6  Sample  Display  List 

Assuming  that  SETDQN  was  called  with  the  qualified  name 
" . WINDOW1 ; " ,  some  qualified  names  you  might  use  to  identify 
elements  in  this  Display  List  are: 

. PSCREN. SCREEN<0> . F0RM1 . WINDOW1<0> . FORM2 . 12 ;  -  This  is  the 
fully  qualified  name  of  12  on  the  current  page  of  WINDOW1, 
which  is  on  the  current  page  of  SCREEN. 

. PSCREN . SCREEN<99 > . FORM1 . WINDOWl<98> . FORM2 .12;  -  This  is  the 
fully  qualified  name  of  12  on  page  98  of  WINDOW1,  which  is  on 
page  99  of  SCREEN. 

. FORM1 . 12 ;  -  This  identifies  the  item  12  on  FORM1. 

. FORM1 ;  -  This  identifies  the  form  FORM1 . 

.13;  -  This  identifies  the  item  13. 

.WINDOWl;  -  This  identifies  the  window  WINDOWl. 

.14(3);  -  This  identifies  the  third  occurrence  of  the  item 
14  . 

12;  -  This  identifies  the  item  12  on  FORM2  in  WINDOWl. 

Some  illegal  names  are: 

I2.FORM2;  because  the  fields  are  specified  in  the  wrong 

order . 

. FORM2 ;  because  FORM2  is  contained  In  two  windows  that  are  at 
the  same  level  in  the  hierarchy. 

3 . 6  Application  Structures 

The  application  structure  should  reflect  the  transaction 
oriented  nature  of  the  Form  Processor  and  follow  the  structure  ot 
the  application  forms.  An  application  can  have  three  possible1 
form  structures: 
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Single  form 

Simple  form  hierarchy 

Complex  form  hierarchy  or  network 
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3.6.1  Single  Form  Structure 

An  application  that  uses  a  single  form  can  do  all  of  its  form 
processing  in  a  "do  forever"  loop.  The  skeleton  structure  for  an 
application  that  uses  a  single  form  is: 

CALL  INITAL 
CALL  INITFP 
CALL  OPNFRM 
CALL  ADDFRM 
initialize  form 
DO  FOREVER 
( 

CALL  PDATA 
CALL  OISCR 

IF  PFKEY  =  QUITKEY  THEN  EXIT  LOOP 
CALL  GDATA 

process  function  key 

} 

CALL  CLSFRM 
CALL  TERMFP 

CALL  TRMNAT  (or  TRMNDML) 

3.6.2  Simple  Form  Hierarchy 

In  an  application  that  uses  a  simple  form  hierarchy,  all 
forms  are  added  to  the  window  SCREN  and  you  only  go  up  and  down 
the  hierarchy.  The  main  module  in  this  application  is  similar  to 
the  single  form  application  except  for  the  do  forever  loop.  With 
a  simple  form  hierarchy,  there  is  one  module  for  each  form  and  the 
main  module  calls  the  first  form  module.  Each  form  module  then 
adds  its  form,  initializes  it,  processes  it,  and  either  calls  the 
module  for  a  form  in  the  next  level  of  the  hierarchy  or  returns  to 
the  module  from  the  previous  level.  The  skeleton  structure  for  a 
form  module  is: 

CALL  ADDFRM 
initialize  form 
DO  FOREVER 
{ 

CALL  PDATA 
CALL  OISCR 

IF  PFKEY  =  QUITKEY  THEN  EXIT  LOOP 

< 

CALL  GDATA 

process  function  key 
) 

IF  return_to_previous_f orm  THEN  EXIT  LOOP 
CALL  next_f orm_module 
) 

CALL  RMVPAG 
RETURN 
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3.6.3  Complex  Form  Hierarchy 

In  an  application  that  uses  a  complex  form  hierarchy  or 
network  of  forms,  forms  can  be  added  to  any  window  in  the 
hierarchy  and  you  can  go  across  the  hierarchy  as  well  as  up  and 
down  it.  The  main  module  in  this  application  is  a  transaction 
dispatcher  that  does  the  call  to  OISCR  and  interprets  the  function 
keys.  There  is  still  one  module  for  each  form  and  the  main  module 
tells  the  form  routine  whether  to  initialize,  process,  or 
terminate.  The  skeleton  structure  for  the  main  module  is: 

CALL  INITAL 
CALL  INITFP 

CALL  f irst_f orm_rout ine ( INIT) 

DO  FOREVER 

{ 

CALL  OISCR 

CALL  GWINDO (window,  page) 

CALL  GPAGE (window,  page,  current_f orm) 

IF  PFKEY  =  QUITKEY  THEN 

{ 

CALL  current_form_routine (TERM) 

IF  page  =  1  THEN  EXIT  LOOP 
) 

CALL  current_form_rout ine ( PROC) 

IF  next_form  !=  current_form  THEN 
( 

IF  NOT  nested  THEN  CALL  current_f orm_rout ine (TERM) 

ELSE  CALL  next_f orm_rout ine ( INIT) 

) 

) 


The  skeleton  structure  for  a  form  module  is: 

SWITCH  (action) 

( 

CASE  INIT: 

CALL  ADDFRM 
initialize  form 
CALL  PDATA 
CASE  PROC: 

CALL  GDATA 
process  form  data 
CALL  PDATA 
CASE  TERM: 

CALL  RMVPAG 

> 

RETURN 

Figure  3-7  shows  the  appearance  of  the  module  hierarchy  for 
this  type  of  application: 
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Figure  3-7 


Module  Hierarchy 


3 . 7  Error  Handling 

The  FP  supports  two  ways  of  indicating  to  the  application 
user  that  an  error  has  occurred.  The  routine  PUTATT  can  be  used 
to  highlight  item  fields  in  error  by  temporarily  changing  their 
display  attributes  and  error  messages  can  be  put  in  the  last  line 
of  the  form  PSCREN  by  the  Form  Processor  or  the  application 
program.  When  creating  forms,  the  last  line  of  the  physical 
terminal  screen  lot  contain  any  form  data. 

To  write  r  this  line  from  your  application,  call  one  of  the 
two  routines  tuat  store  the  message  line  (PMSGLC  or  PMSGLS)  and 
then  output  the  form  to  the  terminal  using  OUTSCR  or  OISCR. 

PMSGLS  p^ces  a  character  string  in  the  message  line.  PMSGLC 
accepts  a  code  which  corresponds  to  a  message  string  that  resides 
in  a  frle.  This  file  is  pre-defined  and  can  be  created  and 
maintained  using  the  User  Interface  tool  Message  Management. 
INCGEN  is  another  UI  tool  that  is  then  used  to  generate  include 
files  containing  message  code  declarations.  Figure  3-8 
illustrates  this  type  of  error  handling. 
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Figure  3-8  Message  Management  Scenario 
for  Error  Handling 


It  is  advisable  to  use  the  message  management  tools  as  much 
as  possible  since  they  allow  you  to  change  the  contents  of  a 
message  without  changing  application  code.  The  use  of  PMSGLS 
should  be  limited  to  those  occasions  when  the  content  of  the 
message  is  determined  at  run-time. 

The  application  message  queue  can  be  viewed  using  the 
<MESSAGE  QUEUE>  key  ( PF3 )  as  described  in  the  IISS  Terminal 
Operator  Guide.  The  Form  Processor  or  System  Message  queue  is 
displayed  using  the  <SYSMSG>  key  in  status  mode. 

3 . 8  Paging  and  Scrolling 

Paging  and  scrolling  is  a  capability  of  the  FP  that  allows  a 
form  to  contain  more  data  than  will  fit  on  the  screen  at  one  time 
with  provisions  for  viewing  any  portion  of  the  data  buffer. 

Paging  and  scrolling  can  be  performed  on  those  fields  which  have 
been  defined  as  scrolling  arrays.  These  are  arrays  which  have 
been  defined  with  an  actual  size  greater  than  the  display  size.  A 
scroll  will  advance/backup,  by  one  element,  the  elements  of  the 
array  that  are  displayed.  A  page  is  some  multiple  of  scrolls, 
usually  equal  to  the  display  size.  An  exception  occurs  when  the 
displayed  elements  are  within  a  display  size  of  an  actual  size 
endpoint.  In  this  case,  a  page  will  scroll  to  the  end  of  the 
array.  Scrollable  arrays  are  especially  useful  for  those 
applications  which  must  display  a  list  of  objects  from  a  database 
or  file  and  the  list  is  larger  than  the  display  area. 

The  paging  and  scrolling  function  keys  are  active  when  the  FP 
is  in  "scrll/page"  mode  as  described  in  the  Terminal  Operator 
Guide . 
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3 . 9  Logical  Devices 

A  logical  device  is  a  conceptual  device  that  is  viewed  by  an 
application  as  a  unique  Display  List.  There  can  be  mere  than  one 
logical  device  on  a  physical  device.  An  application  is  assigned 
one  logical  device  when  the  routine  INITFP  (INITialize  Form 
Processor)  is  called  at  start  up.  During  processing,  the 
application  may  create  and  manipulate  other  logical  devices  by 
calling  the  routines  OPNLDV,  CHGLDV ,  INQLDV,  and  CLSLDV.  The 
logical  device  whose  Display  List  is  being  manipulated  is  referred 
to  as  the  current  logical  device. 

The  routine  CHGLDV  causes  the  logical  device  specified  as  an 
input  parameter  to  become  the  current  logical  device.  This 
logical  device  continues  to  be  current  until  CHGLDV  is  called 
again  and  another  device  is  named  as  an  input  parameter. 

Logical  devices  provide  the  mechanism  for  implementing  pop-up 
menus  in  an  application.  To  do  this,  you  would  define  application 
help  for  an  item  field.  When  the  help  key  is  pressed,  the 
application  could  then  open  a  new  logical  device,  and  display  the 
appropriate  menu  of  options  for  the  field.  When  the  user 
positions  the  cursor  on  the  desired  choice  and  presses  the  <ENTER  ■ 
key,  the  application  can  determine  the  menu  pick  and  continue 
processing.  Logical  devices  are  also  used  to  distinguish  between 
multiple  applications  running  concurrently  on  a  physical  device. 

3.10  Creating  and  Modifying  Forms  at  Run-Time 

Forms  can  be  created  and  modified  at  run-time  using  FP 
routines.  This  provides  a  great  deal  of  flexibility  to  the  user 
interface  of  an  interactive  application.  The  routines  that 
provide  this  capability  are  based  on  the  syntax  of  the  Form 
Definition  Language.  A  thorough  understanding  of  the  material  on 
defining  forms  presented  in  the  Form  Editor  User's  Manual  is 
essential  to  using  these  routines. 

To  modify  an  existing  form  at  run-time,  the  form  must  be 
open.  The  changes  are  made  to  the  form  on  the  Open  List  and  then 
the  changes  are  made  to  all  instances  of  the  form  on  the  Display 
List . 
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FP  CALLABLE  ROUTINES 


This  section  of  the  manual  describes  the  callable  FP 
routines.  They  are  listed  alphabetically  with  a  brief  functional 
description . 

ROUTINE  FUNCTION 


ADDDIM 

ADDELM 

ADDFLD 

ADDFRM 

APRFLD 

CHGLDV 

CLSFRM 

CLSLDV 

CRTFLD 

CRTFRM 

GDATA 

GDATLN 

GDPFEX 

GDPFLC 

GETATT 

GETBAK 

GETCUR 

GETDQN 

GETLDV 

GETVTI 

GFMFLD 

GPAGE 

GTUINF 

GTUSYM 

GWINDO 

INITFP 

INITVT 

INQABS 

INQAPR 

INQATT 

INQDIM 

INQDIS 

INQDOM 

INQHLP 

INQLDV 

INQLOC 

INQPRO 

INQSIZ 


Add  an  array  dimension  to  a  field. 

Add  an  element  to  the  end  of  an  open  ended  array. 

Add  a  field  with  specified  characteristics  to  all 
instances  of  a  form. 

Add  a  form  to  a  window. 

Make  a  field  appear  or  disappear. 

Change  the  logical  device  associated  with  the  current 
Display  List. 

Close  a  form. 

Close  a  logical  device. 

Add  a  field  with  default  characteristics  to  all 
instances  of  a  form. 

Create  an  empty  form. 

Get  data  from  a  Display  List  element. 

Get  data  length. 

Identify  field  whose  value  depends  on  the  specified 
f ield . 

Identify  field  whose  horizontal  location  depends  on  the 
specified  field. 

Get  an  item  attribute. 

Get  form  or  window  background. 

Get  the  current  cursor  position. 

Get  default  qualified  name. 

Get  logical  device. 

Get  application  data  from  the  Virtual  Terminal. 

Return  the  name  and  type  of  a  field  on  a  form. 

Get  form  on  page. 

Get  user  information. 

Return  prototype  strings  for  IISSSLIB  and  IISSULIB. 

Get  window  information. 

Initialize  Form  Processor. 

Set  VTI  mode  flag. 

Return  absolute  row  and  column  of  a  field  location. 
Return  a  field's  appears  if  criterion. 

Return  attribute  or  attribute  primitive  values  defined 
for  a  form. 

Return  dimension  information  for  a  field  array. 

Return  the  current  permanent  attribute  of  a  form  or 
field. 

Return  an  item  field's  domain  values. 

Return  item  field's  help  messages. 

Inquire  logical  device. 

Return  relative  location  of  a  field. 

Return  field  prompt  information. 

Retui.ii  field  size  information. 
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INQTYP  Return  field  type  information. 

INQVAL  Return  field  value  expression  information. 

MAKFRM  Create  a  form  with  specified  size  and  attribute. 

MOVLDV  Move  logical  device 

MVRFLD  Copy  a  field  specifying  name  and  location. 

NUMELM  Return  elements  in  open-ended  array. 

OISCR  Output  a  screen  and  wait  for  input. 

OPNFRM  Open  a  form. 

OPNLDV  Open  a  logical  device. 

OUTSCR  Output  a  screen. 

PARFQN  Parse  a  qualified  name. 

PDATA  Put  data  in  a  Display  List  element. 

PMSGLC  Put  the  message  corresponding  to  the  code  into  the 
message  line. 

PMSCLS  Put  a  string  into  the  message  line. 

PUTATT  Put  an  item  attribute. 

PUTBAK  Put  a  form  or  window  background. 

PUTCUR  Put  the  cursor  in  a  specified  field  position. 

PUTLOC  Put  the  cursor  in  a  specified  location  within  a  field. 

PUTVTI  Send  application  data  to  Virtual  Terminal. 

REPFLD  Copy  field  with  default  location. 

REPFRM  Copy  form  specifying  new  name. 

RMVAPR  Remove  a  field's  appears  if  criterion. 

RMVARY  Remove  all  field  array  dimensions. 

RMVATT  Remove  form  attribute. 

RMVDIM  Remove  a  field  array  dimension. 

RMVDOM  Remove  item  field  domain  options. 

RMVFLD  Remove  field  from  a  form. 

RMVHLP  Remove  item  field  help. 

RMVPAG  Remove  a  page  from  a  window. 

RMVPRO  Remove  form  or  field  prompt  text. 

RMWAL  Remove  an  item  field's  value  expression. 

RPLFRM  Replace  a  form. 

SAVFRM  Save  dynamically  created  or  modified  forms. 

SETAPR  Specify  a  field's  appears  if  criterion. 

SETATT  Set  or  change  form  attribute  primitives. 

SETDIM  Change  a  specified  field  array  dimension. 

SETDIS  Specify  item  field  display  attribute. 

SETDOM  Specify  item  field  domain  options. 

SETDQN  Set  the  default  qualified  name. 

SETHLP  Specify  item  field  help. 

SETLDV  Specify  logical  device  display  parameters. 

SETLOC  Specify  field  location. 

SETNAM  Specify  field  name. 

SETPRO  Add  form  or  field  prompt. 

SETSIZ  Specify  field  size. 

SETTYP  Specify  field  type. 

SETVAL  Define  an  item  field's  value  expression. 

TERMFP  Terminate  Form  Processor. 

TERMVT  Clear  VTI  mode  flag. 

The  use  of  each  routine  is  explained  in  detail  in  the 
following  sections.  This  includes  a  description  of  the  routine's 
purpose,  the  format  fr -  calling  the  routine,  descriptions  of  the 
calling  parameters,  a’  in  example  call.  Note  that  the  calling 
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formats  and  examples  are  given  in  C,  and  Str  and  Num  in  the 
parameter  format  mean  character  string  and  long  integer.  Example 
data  types  in  COBOL,  PL1 ,  C,  and  Fortran  are: 


COBOL 

PL1 

C 

FORTRAN 

Num 

S9 (5)  COMP 

FIXED  BIN (31) 

int 

INTEGER 

Str 

PIC  X ( n) 

CHAR (N) 

char [ n ] 

CHARACTER*N 

Note:  A  C  character  string  may  contain  the  null  character  if  it 
is  after  the  last  character  the  FP  looks  at  (i.e.,  after  the 
semicolon  in  a  qualified  name) . 
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4 . 1  ADDDIM 

This  routine  is  used  to  add  an  array  dimension  to  a  field  at 
run-time.  The  routine  parameters  correspond  to  the  components  of 
the  Repeat  Specification  syntax  described  in  the  Form  Editor 
User's  Manual. 

4.1.1  Calling  Format 

CALL  "ADDDIM"  USING  FORM-NAME, 

FIELD-NAME, 

DISPLAY-SIZE, 

ACTUAL-SIZE, 

DIRECTION, 

SPACES, 

RCODE . 


NAME 

I/O 

FORMAT 

DEFINITION 

FORM-NAME  | 

Input  | 

Str (10) | 

The  name  of  the  containing  form 

FIELD-NAME 

Input 

Str (10) 

The  name  of  the  field  to  define 
an  array  dimension  for. 

DISPLAY- 

SIZE 

Input 

Num 

The  number  of  field  repetitions 
to  display  on  the  form. 

ACTUAL- 

SIZE 

Input 

Num 

The  total  number  of  times  the 
field  actually  repeats. 

DIRECTION 

Input 

Str ( 1) 

A  character  code  that  specifies 
the  repeat  direction.  Values 
are  H  -  Horizontal  and  V  - 
Vertical . 

SPACES 

Input 

Num 

The  number  of  spaces  to  leave 
between  field  repetitions. 
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H - 1 - 1 - 1 - +- 

RCODE  Output  Str(5)  The  routine  return  code.  The 

possible  values  are  defined  in 
the  include  member  FPCODE. 

+ - + - + - + - + 


4.1.3  Example 


WORKING-STORAGE  SECTION. 
COPY  FPCODE  OF  IISSCLIB. 
COPY  FPPARM  OF  IISSCLIB. 


01 

EXPFRM-NAME 

PIC 

X(10) 

VALUE 

"EXPFRM" . 

01 

TSTFLD-NAME 

PIC 

X(10) 

VALUE 

"TSTFRD" . 

01 

DSP-SIZE 

PIC 

S9  ( 5 ) 

COMP 

VALUE  10. 

01 

ACT-SIZE 

PIC 

S9  ( 5 ) 

COMP 

VALUE  20. 

01 

NUM-SPACES 

PIC 

S9  ( 5 ) 

COMP 

VALUE  0. 

01 

RPT-DIRECTION 

PIC 

X  VALUE  "V" 

PROCEDURE  DIVISION. 


CALL  "ADDDIM"  USING  EXPFRM-NAME , 

TSTFLD-NAME , 
DSP-SIZE , 
ACT-SIZE, 
NUM-SPACES, 
RPT-DIRECTION , 
RCODE . 

IF  RCODE  IS  EQUAL  TO  OK 


ELSE 

CALL  "PMSGLC"  USING  RCODE. 
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4.2  ADDELM 


This  routine  is  used  to  add  an  element  to  the  end  of  an 
open-ended  array.  An  open-ended  array  is  one  which  is  defined 
with  length  *  instead  of  an  integer  number  of  rows.  The  Form 
Editor  User's  Manual  describes  the  syntax  for  defining  arrays. 

4.2.1  Calling  Format 

CALL  "ADDELM"  USING  QUALIFIED-NAME, 

ELEMENT-NUMBER, 

RCODE . 

4.2.2  Parameter  Descriptions 

NAME  I/O  FORMAT  DEFINITION 


t- - H 

QUALIFIED- 

NAME 

h - H 

Input 

h - H 

Str (1-120) 

h - 

The  name  of  the  array  that 
you  want  to  add  the  element 
to. 

ELEMENT- 

NUMBER 

Output 

Num 

The  number  of  the  element 
that  was  added  to  the  array. 

RCODE 

Output 

— 

Str (5) 

- H 

The  routine  return  code.  The 
possible  values  are  defined 
in  the  include  member 

FPCODE . 
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ADDELM 


WORKING-STORAGE  SECTION. 

COPY  FPCODE  OF  IISSCLIB. 

COPY  FPPARM  OF  IISSCLIB. 

01  PATH-NAME  PIC  X(ll)  VALUE  "EXPFRM . ARY ; " . 

01  ELEMENT-NUMBER  PIC  S9(5)  COMP. 

PROCEDURE  DIVISION. 


CALL  "ADDELM"  USING  PATH-NAME, 

ELEMENT-NUMBER, 
RCODE . 

IF  RCODE  IS  EQUAL  TO  OK 


ELSE 

CALL  " PMSGLC"  USING  RCODE. 
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4 . 3  ADDFLD 


This  routine  is  used  to  add  a  field  to  a  form  at  run-time 
with  the  location,  size,  type,  and  display  attribute  you  specify. 
The  field  is  added  to  all  instances  of  the  form  currently  on  the 
Display  List.  It  will  also  appear  on  any  subsequent  instances  of 
the  form  added  to  the  Display  List. 

4.3.1  Calling  Format 

CALL  "ADDFLD"  USING  FORM-NAME, 

FIELD-NAME, 

FIELD-TYPE, 

ATTRIBUTE-ID, 

WIDTH, 

DEPTH, 

VREL-FIELD , 

VEXTREF, 

VINTREF, 

ROW, 

HREL-FIELD, 

HEXTREF, 

HINTREF, 

COLUMN , 

RCODE . 
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4.3.2  Parameter  Descriptions 


NAME  I/O  FORMAT  DEFINITION 

FORM-NAME 

Input 

Str ( 10) 

The  name  of  the  form  that  the 
new  field  is  being  added  to. 

FIELD-NAME 

Input 

Str ( 10) 

The  name  of  the  field  being 
added . 

FIELD-TYPE 

Input 

1 

Str  ( 1) 

A  character  code  to  identify 
the  type  of  field  being  added. 
Values  are:  W  -  window,  F  - 
form,  and  I  -  item. 

ATTRIBUTE- 

ID 

Input 

Str ( 10) 

The  attribute  value  to  be 
associated  with  the  new  field. 
This  can  be  a  user-defined  at¬ 
tribute  or  one  of  the  pre¬ 
defined  values  defined  in  the 
include  member  FPPARM. 

WIDTH 

!- - H 

Input 

h - H 

Num 

The  number  of  columns  wide  the 
field  is . 

DEPTH 

Input 

1 

Num 

The  number  of  rows  high  the 
field  is. 

VREL- 

FIELD 

Input 

Str 

(1-120) 

The  qualified  name  of  the  field 
that  FIELD-NAME's  position  is 
vertically  relative  to  or  blank 
if  it  is  relative  to  its  con¬ 
taining  form. 

VEXTREF 

Input 

Num 

The  vertical  reference  point 
on  VREL-FIELD  that  FIELD-NAME's 
position  is  relative  to.  Values 
are  1  -  top,  2  -  center,  and 

3  -  bottom.  j 

VINTREF 

+ - H 

Input 

h - -! 

Num 

i 

- 

The  vertical  reference  point  of 
FIELD-NAME  that  its  position  is 
relative  to.  Values  are  the 
same  as  for  VEXTREF. 
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- _l 

ROW 

- -l 

Input 

- 1 

Num 

The  number  of  rows  that  FIELD- 
NAME'S  position  is  offset  from 
VREL-FIELD's  reference  point. 

HREL- 

FIELD 

Input 

Str 

(1-120) 

The  qualified  name  of  the  field 
that  FIELD-NAME's  position  is 
horizontally  relative  to  or 
blank  if  it  is  relative  to  the 
containing  form. 

HEXTREF 

Input 

Num 

The  horizontal  reference  point 
on  HREL-FIELD  that  FIELD-NAME's 
position  is  relative  to.  Values 
are  1  -  left,  2  -  center,  and 

3  -  right. 

HINTREF 

Input 

Num 

The  horizontal  reference  point 
of  FIELD-NAME  that  the  position 
is  relative  to.  Values  are  the 
same  as  for  HEXTREF. 

COLUMN 

Input 

Num 

The  number  of  columns  the  field 
is  offset  from  HREL-FIELD' s 
reference  point. 

RCODE 

Output 

- 

Str (5) 

H - 

The  routine  return  code.  The 
possible  values  are  defined  in 
the  include  member  FPCODE. 

4.3.3  Example 


WORKING-STORAGE  SECTION. 
COPY  FPCODE  OF  IISSCLIB. 
COPY  FPPARM  OF  IISSCLIB. 


01 

EXPFRM-NAME 

PIC 

X(10) 

VALUE 

" EXPFRM" . 

01 

NEWFLD-NAME 

PIC 

X(10) 

VALUE 

"NEWITEM" . 

01 

NEWFLD-TYPE 

PIC 

X(l) 

VALUE 

"I"  . 

01 

NEWFLD- WIDTH 

PIC 

S9  ( 5 ) 

COMP 

VALUE 

10  . 

01 

NEW FLD- DEPTH 

PIC 

S9  ( 5 ) 

COMP 

VALUE 

1  . 

01 

REF-FLD-NAME 

PIC 

X  ( 7 ) 

VALUE 

"TSTFLD ; " . 

01 

TOP-LEFT-REF 

PIC 

S9(5) 

COMP 

VALUE 

1  . 

01 

CENTER-REF 

PIC 

S9(5) 

COMP 

VALUE 

2  . 

01 

BOT-RIGHT-REF 

PIC 

S9  ( 5 ) 

COMP 

VALUE 

3  . 

01 

ZERO-COMP 

PIC 

S9  ^  5 ) 

COMP 

VALUE 

0  . 

01 

TWO-COMP 

PIC 

S9  ( 5 ) 

COMP 

VALUE 

2  . 
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ADDELM 


PROCEDURE  DIVISION. 


CALL  "ADDFLD"  USING  EXPFRM-NAME, 

NEWFLD-NAME, 
NEWFLD-TYPE , 

INP, 

NEWFLD-WIDTH , 

NEWFLD-DEPTH , 

REF-FLD-NAME , 

BOT-RIGHT-REF, 

TOP-RIGHT-REF, 

TWO-COMP, 

REF-FLD-NAME, 

CENTER-REF, 

CENTER-REF, 

ZERO-COMP, 

RCODE . 

IF  RCODE  IS  EQUAL  TO  OK 


ELSE 

CALL  "PMSGLC"  USING  RCODE. 
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4 . 4  ADDFRM 

This  routine  adds  a  form  to  a  window.  The  window  you  are 
adding  the  form  to  must  already  be  on  the  Display  List.  If  the 
form  is  not  already  open,  it  will  be  opened  automatically .  Adding 
a  form  to  a  window  creates  a  new  page. 

4.4.1  Calling  Format 

CALL  "ADDFRM"  USING  QUALIFIED-WINDOW-NAME, 

FORM-NAME, 

PAGE-NUMBER, 

RCODE . 

4.4.2  Parameter  Descriptions 


NAME  I/O  FORMAT  DEFINITION 

QUALIFIED- 

WINDOW- 

NAME 

Input 

Str (1-120) 

The  qualified  name  oi  the 
Display  List  element  that 
identifies  the  window  that 
will  contain  the  form. 

FORM-NAME 

Input 

Str  (10) 

The  name  of  the  form  being 
added . 

PAGE- 

NUMBER 

Output 

Num 

The  number  of  the  page  that 
the  added  form  creates  in 
the  window. 

RCODE 

Output 

i- - 

Str  ( 5) 

i- - 

The  routine  return  code.  The 
possible  values  are  defined 
in  the  include  member 

FPCODE . 

(- - + 
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ADDFRM 


4.4.3  Example 

WORKING-STORAGE  SECTION. 

COPY  FPCODE  OF  IISSCLIB. 

COPY  FPPARM  OF  IISSCLIB. 

01  PAGE-NUMBER  PIC  S9(5)  COMP. 
01  EXPFRM-NAME  PIC  X(10)  VALUE 
PROCEDURE  DIVISION. 


CALL  "ADDFRM"  USING  SCREN, 

EXPFRM-NAME, 
PAGE-NUMBER, 
RCODE . 

IF  RCODE  IS  EQUAL  TO  OK 


ELSE 

CALL 


"PMSGLC" 


USING  RCODE. 


"EXPFRM" . 
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4 . 5  APRFLD 


This  routine  allows  you  to  control  when  a  field  appears  or 
does  not  appear  on  its  containing  form.  The  APR-FLAG  can  be  set 
to  display  the  field,  not  display  the  field,  or  toggle  (i.e.,  do 
the  opposite  of  what  the  current  setting  is) .  The  effect  of  this 
routine  takes  place  at  the  next  OISCR.  If  a  loop  that  contains  a 
call  to  OISCR  is  preceded  by  a  call  to  APRFLD  to  toggle  the 
setting,  the  setting  will  remain  the  same  for  all  the  OISCR  calls. 
If  the  call  to  APRFLD  is  also  inside  the  loop,  the  APR-FLAG 
setting  will  toggle  for  each  call  to  OISCR.  NOTE  that  any  appears 
if  criterion  defined  for  the  field  is  evaluated  during  an  OISCR 
and  therefore,  will  cancel  the  APR-FLAG  setting.  If  an  item  field 
has  a  location  of  0  0  (i.e.,  it  is  non-display),  a  location  must 
be  defined  for  the  field  before  APRFLD  can  be  called  to  display 
the  field. 

4.5.1  Calling  Format 

CALL  "APRFLD"  USING  QUALIFIED-NAME, 

APR-FLAG, 

RCODE . 

4.5.2  Parameter  Descriptions 

NAME  I/O  FORMAT  DEFINITION 


- -1 

QUALIFIED- 

NAME 

- - H 

Input 

- H 

Str (1-120) 

The  qualified  name  of  the 
Display  List  element  that 
identifies  the  field. 

APR-FLAG 

Input 

Str ( 1) 

A  character  code  to  specify 
the  appear  flag  setting. 
Values  are  A  -  Appears,  D  - 
Disappear,  and  T  -  Toggle. 

RCODE 

Output 

h - - 

Str (5) 

v - 

The  routine  return  code.  The 
possible  values  are  defined 
in  the  include  member 

FPCODE . 

L - 
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APRFLD 


4.5.3  Example 

WORKING-STORAGE  SECTION. 

COPY  FPCODE  OF  IISSCLIB. 

COPY  FPPARM  OF  IISSCLIB. 

01  FLAG  PIC  X. 

01  PATH-NAME  PIC  X(7)  VALUE  "MYFO^-';  ’  . 

PROCEDURE  DIVISION. 


CALL  "APRFLD"  USING  PATH-NAME, 

FLAG, 

RCODE . 

IF  RCODE  IS  EQUAL  TO  OK 


ELSE 

CALL  " PMSGLC"  USING  RCODE. 
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4 . 6  CHGLDV 

This  routine  is  used  to  make  the  Display  List  associated  with 
the  specified  logical  device  the  current  Display  List.  After 
CHGLDV  is  called,  all  form  processing  is  done  on  the  named  logical 
device  until  it  is  called  again  with  a  different 
logical -dev ice -id . 

NOTE:  If  you  are  changing  from  the  initial  logical  device  assigned 
at  start  up  and  you  intend  to  return  processing  to  it  at  a  later 
time,  you  need  to  call  INQLDV  to  determine  its  logical-device- id 
before  you  call  CHGLDV. 

4.6.1  Calling  Format 

CALL  "CHGLDV"  USING  LOGICAL-DEVICE- I D , 

RCODE . 

4.6.2  Parameter  Descriptions 

NAME  I/O  FORMAT  DEFINITION 


LOGICAL- 

DEVICE-ID 

i - 1 

Input 

Num 

The  ID  of  the  logical  device 
that  you  want  to  be  the  current 
display  list.  The  logical-dev- 
ice-id  is  returned  when  you 
call  OPNLDV  to  create  a  logical 
device. 

RCODE 

Output 

h - H 

Str (5) 

i - 

The  routine  return  code.  The 
possible  values  are  defined  in 
the  include  member  FPCODE. 

h - 
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CHGLDV 


4.6.3  Example 

WORKING-STORAGE  SECTION. 

COPY  FPCODE  OF  IISSCLIB. 

COPY  FPPARM  OF  IISSCLIB. 

01  LOGICAL-DEVICE-ID  PIC  S9(5)  COMP. 
PROCEDURE  DIVISION. 


CALL  "CHGLDV"  USING 
LOG I CAL- DEV I CE - I D , 

RCODE . 

IF  RCODE  IS  EQUAL  TO  OK 


ELSE 

CALL  "PMSGLC"  USING  RCODE. 
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4 . 7  CLSFRM 

This  routine  is  used  to  close  a  form.  This  means  that  the 
memory  that  was  used  by  this  form  while  the  application  had  it 
open  (see  OPNFRM)  is  released  so  that  it  may  be  allocated  to 
another  form.  In  order  to  close  a  form,  it  must  not  be  in  a 
window  (i.e.,  it  was  never  in  a  window,  it  was  removed  from  the 
window  using  RMVPAG,  or  it  was  replaced  using  RPLFRM)  and  it  must 
not  be  a  subform  on  any  other  open  forms.  NOTE  that  if  an  open 
form  is  changed  at  run-time,  the  routine  SAVFRM  must  be  called 
before  closing  it  to  save  the  changes. 

4.7.1  Calling  Format 

CALL  "CLSFRM"  USING  FORM-NAME, 

RCODE . 

4.7.2  Parameter  Descriptions 

NAME  I/O  FORMAT  DEFINITION 


- H 

FORM-NAME 

h - H 

Input 

h - -1 

Str (10) 

The  name  of  the  form  being 
closed . 

RCODE 

' 

Output 

i- - \ 

Str (5) 

! 

h - - 

The  routine  return 
possible  values  are 
the  include  member 

code.  The 
defined  in 
FPCODE. 

4.7.3  Example 

WORKING-STORAGE  SECTION. 

COPY  FPCODE  OF  IISSCLIB. 

COPY  FPPARM  OF  IISSCLIB. 

01  EXPFRM-NAME  PIC  X(10)  VALUE  "EXPFRM" . 
PROCEDURE  DIVISION. 


CALL  "CLSFRM"  USING  EXPFRM-NAME, 

RCODE. 

IF  RCODE  IS  EQUAL  TO  OK 


ELSE 

CALL  " PMSGLC"  USING  RCODE. 
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4.8  CLSLDV 

CLSLDV  is  used  to  close  a  logical  device.  When  a  logical 
device  is  closed,  the  Display  List  associated  with  it  is  removed 
from  memory.  You  cannot  close  the  original  logical  device  that  is 
created  by  INITFP  or  the  logical  device  associated  with  the 
current  Display  List.  In  that  case,  you  must  call  CHGLDV  to 
associate  a  different  device  with  the  current  Display  List. 

4.8.1  CALLING  FORMAT 

CALL  "CLSLDV”  USING  LOGICAL-DEVICE-ID, 

RCODE . 

4.8.2  Parameter  Descriptions 


NAME  I/O  FORMAT  DEFINITION 

H - - - —  —  — - —  —  +  — - H —  —  — - — - - - — - h 


LOGICAL- 

DEVICE-ID 

Input 

Str (10) 

The  id  of  the  logical  device 
that  you  want  to  close.  You 
obtain  the  logical-device-id  of 
the  device  when  you  create  the 
device  using  OPNLDV. 

RCODE 

Output 

Str (5) 

The  routine  return  code.  The 

possible  values  are  defined  in 
the  include  member  FPCODE. 

4.8.3  Example 

WORKING-STORAGE  SECTION. 

COPY  FPCODE  OF  IISSCLIB. 

COPY  FPPARM  OF  IISSCLIB. 

01  LOGICAL-DEVICE-ID  PIC  S9(5)  COMP. 
PROCEDURE  DIVISION. 


CALL  "CLSLDV"  USING 
LOGICAL-DEVICE-ID, 

RCODE. 

IF  RCODE  IS  EQUAL  TO  OK 


ELSE 

CALL  " PMSGLC"  USING  RCODE. 
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4 . 9  CRTFLD 


This  routine  adds  a  field  to  all  instances  of  an  open  form  at 
run-time.  Required  field  characteristics  have  default  values. 

The  field  is  a  non-displayed  ITEM.  This  means  that  the  location 
must  be  specified  using  the  routine  SETLOC  in  order  for  the  item 
to  appear  on  the  screen.  The  size  of  the  field  defaults  to  one 
and  its  display  attribute  is  text.  Other  routines  may  be  used  to 
change  these  defaults  or  further  define  the  field  to  include  such 
things  as  prompts,  help,  and  array  dimensions. 

4.9.1  Calling  Format 

CALL  "CRTFLD"  USING  FORM-NAME, 

FIELD-NAME, 

RCODE . 


4.9.2  Parameter  Descriptions 


NAME 

I/O 

FORMAT 

DEFINITION 

FORM-NAME 

Input 

Str (10) 

The  name  of  the  form  that  the 
new  field  is  being  added  to. 

FIELD-NAME 

Input 

Str ( 10) 

The  name  of  the  field  that  is 
being  added  to  the  form. 

RCODE 

o 

c 

rt 

n 

c 

rt 

n 

C/) 

rt 

<ji 

The  routine  return  code.  The 
possible  values  are  defined  in 
the  include  member  FPCODE. 

+ - + - + - + - + 
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4.9.3  Example 

WORKING-STORAGE  SECTION. 

COPY  FPCODE  OF  IISSCLIB. 

COPY  FPPARM  OF  IISSCLIB. 

01  EXPFRM-NAME  PIC  X(10)  VALUE  "EXPFRM". 
01  NEWFLD-NAME  PIC  X(10^  VALUE  "NEWFLD" . 
PROCEDURE  DIVISION. 


CALL  "CRTFLD"  USING  EXPFRM-NAME, 

NEWFLD-NAME, 

RCODE . 

IF  RCODE  IS  EQUAL  TO  OK 


ELSE 

CALL  " PMSGLC"  USING  RCODE. 
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4.10  CRTFRM 


This  routine  creates  a  new  form  at  run-time.  The  background 
attribute  is  transparent  and  the  size  defaults  to  0  0  meaning  it 
is  not  a  fixed  size.  Other  routines  may  be  used  to  override  these 
defaults  or  further  define  the  form  to  include  such  things  as 
prompts,  fields,  and  particular  attributes.  The  form  is  open. 

4.10.1  Calling  Format 

CALL  "CRTFRM"  USING  FORM-NAME, 

RCODE . 

4.10.2  Parameter  Descriptions 

NAME  I/O  FORMAT  DEFINITION 

+ - + - + - + - + 


FORM-NAME 

Input 

str ( 10) 

The  name  of  the  new  form  being 
created . 

RCODE 

Output 

Str  ( 5) 

The  routine  return  code.  The 
possible  values  are  defined  in 
the  include  member  FPCODE. 

•4 - —  —  —  — - +  — - - -4 - f*  — - - - + 


4.10.3  Example 

WORKING-STORAGE  SECTION. 

COPY  FPCODE  OF  IISSCLIB. 

COPY  FPPARM  OF  IISSCLIB. 

01  NEWFRM-NAME  PIC  X(10)  VALUE  "NEWFORM" . 
PROCEDURE  DIVISION. 


CALL  "CRTFRM"  USING  NEWFRM-NAME, 

RCODE. 

IF  RCODE  IS  EQUAL  TO  OK 


ELSE 

CALL  " PMSGLC"  USING  RCODE. 
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4.11  GDATA 


This  routine  is  used  to  access  user  entered  data  from  an 
element  on  the  current  Display  List.  The  location  of  the  data  is 
specified  by  a  qualified  name  as  explained  in  section  3.4  of  this 
manual.  The  specified  element  cannot  be  a  window.  This  means 
that  the  data  must  be  from  a  form  or  an  item.  If  the  Display  List 
element  is  an  array,  you  will  aet  the  data  from  all  the  array 
elements  unless  you  specify  a  specific  one.  You  can  also  specify 
whether  you  want  the  current  or  previous  instance  of  the  data.  By 
comparing  the  current  and  previous  instance  of  data,  you  can  find 
out  what  the  user  has  changed  on  a  form. 

4.11.1  Calling  Format 

CALL  "GDATA"  USING  INSTANCE-ID, 

QUALIFIED-NAME, 

OUTPUT- DATA, 

RCODE . 


4.11.2  Parameter  Descriptions 


NAME 


I/O 


FORMAT  DEFINITION 


INSTANCE-  1 
ID 

Input 

Str(10) 

The  instance  of  the  data  you 
want  to  access.  The  include 
file  FPPARM  contains  the  defin¬ 
ition  for  the  instance-id 
values  PREV  and  CURRNT . 

QUALIFIED- 

NAME 

Input 

Str 

(1-120) 

The  qualified  name  that  identi¬ 
fies  the  Display  List  element 
whose  data  you  want  to  access. 
The  routines  GWINDO  and  GPAGE 
may  have  to  be  used  to  help  you 
define  the  name. 

OUTPUT- 

DATA 


Output 


Var . 


+ - + 

The  data  structure  containing 
the  accessed  data.  You  have  the 
option  of  defining  the  struc¬ 
ture  in  your  application  or 
using  the  structure  defined 
forms  definition  tool  MAKINC 
described  in  the  Form  Editor  UM 
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GDATA 


H —  —  - f 

The  routine  return  code.  The 
possible  values  are  defined  in 
the  include  member  FPCODE. 


RCODE 


Output 


Str (5) 


4.11.3  Example 

WORKING-STORAGE  SECTION. 

COPY  FPCODE  OF  IISSCLIB. 

COPY  FPPARM  OF  IISSCLIB. 

COPY  EXPFRM  OF  IISSCLIB. 
★EXPLANATION  OF  COPY  MEMBER  EXPFRM 
*01  EXPFRM. 


★ 

02 

FIELD1 

PIC 

X(6)  . 

* 

02 

FIELD2 

PIC 

X(10) . 

★ 

02 

FIELD3 

PIC 

X  (  2  )  . 

01 

EXPFRM-NAME 

PIC 

X ( 7 )  VALUE  "EXPFRM;" 

PROCEDURE  DIVISION. 


CALL  "GDATA"  USING  CURRNT , 

EXPFRM-NAME , 

EXPFRM, 

RCODE. 

IF  RCODE  IS  EQUAL  TO  OK 


ELSE 

CALL  " PMSGLC"  USING  RCODE. 
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4.12  GDATLN 


This  routine  is  used  to  determine  the  length  of  data 
contained  in  a  Display  List.  For  instance,  GDATLN  can  be  called 
to  get  the  length  of  the  data  that  would  be  returned  by  a  call  to 
GDATA  or  that  would  be  written  by  a  call  to  PDATA. 

4.12.1  Calling  Format 

CALL  "GDATLN"  USING  QUALIFIED-NAME, 

DATA-LENGTH, 

RCODE . 

4.12.2  Parameter  Descriptions 


NAMF 

I/O 

FORMAT 

DESCRIPTION 

QUALIFIED- 

MAME 

Input 

Str 

(1-120) 

The  gualified  name  of  the  Dis¬ 
play  List  element  that  identi¬ 
fies  the  data  you  want  the 
length  of. 

DATA- 

LENGTH 

Output 

Num 

The  length  of  the  specified 
data . 

RCODE 

- H 

Output 

h - H 

Str (5) 

h - H 

The  routine  return  code.  The 
possible  values  are  defined  in 
the  include  member  FPCODE. 
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GDATLN 


WORKING-STORAGE  SECTION. 

COPY  FPCODE  OF  IISSCLIB. 

COPY  FPPARM  OF  IISSCLIB. 

01  DATA-LEN  PIC  S9(5)  COMP. 

01  PATH-NAME  PIC  X(7)  VALUE  "MYFORM ; " . 

PROCEDURE  DIVISION. 


CALL  "GDATLN"  USING  PATH-NAME, 

DATA-LEN, 

RCODE . 

IF  RCODE  IS  EQUAL  TO  OK 


ELSE 

CALL  "PMSGLC"  USING  RCODE. 
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4.13  GDPFEX 


This  routine  is  used  to  find  the  names  of  fields  on  a 
specified  form  whose  values  depend  on  a  particular  field  on  the 
form. 

4.13.1  Calling  Format 

CALL  "GDPFEX"  USING  FORM-NAME, 

FIELD-NAME, 

FIELD-NUM, 

DEP-FIELD , 

RCODE . 


4.13.2  Parameter  Descriptions 


NAME 


I/O 


FORMAT  DESCRIPTION 


FORM-NAME 


Input 


Str ( 10) 


The  name  of  the  form  that  con¬ 
tains  the  field  that  other 
fields'  values  depend  on. 


FIELD-MAME 

Input 

Str ( 10) 

i 

The  name  of  the  field  that 
other  field's  values  depend  on. 

FIELD-NUM 

Input 

Num 

! 

A  number  which  indicates  which 
field  on  the  form. 

DEP-FIELD 

Output 

Str ( 10 ) 

The  name  of  the  field  whose 
value  depends  on  the  indicated 
field . 

RCODE 

Output 

Str (5) 

The  routine  return  code.  The 
possible  values  are  defined  in 
the  include  member  FPCODE. 

+ - 4- - + - + - + 
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4.13.3  Example 

WORKING-STORAGE  SECTION. 
COPY  FPCODE  OF  IISSCLIB. 
COPY  FPPARM  OF  IISSCLIB. 


01 

EXPFRM-NAME 

PIC 

X(10) 

VALUE  "EXPFRM" . 

01 

TSTFLD-NAME 

PIC 

X(10) 

VALUE  "TSTFLD" . 

01 

FIELD-NUM 

PIC 

S9(5) 

COMP. 

01 

DEPFLD-NAME 

PIC 

X(10) 

. 

PROCEDURE  DIVISION. 


PERFORM  GET-NEXT  VARYING  FIELD-NUM  FROM  ZERO  BY  1 

UNTIL  RCODE  NOT  EQUAL  TO  OK. 


GET-NEXT. 

CALL  "GDPFEX"  USING  EXPFRM-NAME , 

TSTFLD-NAME , 
FIELD-NUM, 
DEPFLD-NAME , 
RCODE. 

IF  RCODE  IS  EQUAL  TO  OK 


ELSE 

CALL  " PMSGLC"  USING  RCODE. 


4-28 


GDPFLC 


UM  62034420U 
30  September  1990 


4 . 14  GDPFLC 

This  routine  is  used  to  find  the  names  of  fields  on  a 
specified  form  whose  locations  depend  on  a  particular  fieid  on  the 
form. 

4.14.1  Calling  Format 

CALL  "GDPFLC"  USING  FORM-NAME, 

FIELD-NAME, 

FIELD-NUM , 

DEP-FIELD , 

RCODE . 


4.14.2  Parameter  Descriptions 


NAME  I/O  FORMAT  DESCRIPTION 

FORM-NAME 

Input 

Str (10) 

The  name  of  the  form  that  con¬ 
tains  the  field  that  other 
fields'  values  depend  on. 

FIELD-MAME 

Input 

Str(10) 

The  name  of  the  field  that 
other  field's  values  depend  on. 

FIELD-NUM 

Input 

Num 

A  number  which  indicates  which 
field  on  the  form. 

DEP-FIELD 

Output 

Str ( 10) 

The  name  of  the  field  whose 
value  depends  on  the  indicated 
f ield . 

RCODE 

1  Output 

1  Str ( 5) 

The  routine  return  code.  The 

possible  values  are  defined  in 
j the  include  member  FPCODE. 

+ - + - 4- - + - + 
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GDPFLC 


WORKING-STORAGE  SECTION. 
COPY  FPCODE  OF  IISSCLIB. 
COPY  FPPARM  OF  IISSCLIB. 


01 

EXPFRM-NAME 

PIC 

X  ( 10) 

VALUE  " EXPFRM" 

01 

TSTFLD-NAME 

PIC 

X(10) 

VALUE  "TSTFLD" 

01 

FIELD-NUM 

PIC 

S9  (  5 ) 

COMP. 

01 

DEPFLD-NAME 

PIC 

X(10) 

. 

PROCEDURE  DIVISION. 


PERFORM  GET-NEXT  VARYING  FIELD-NUM  FROM  ZERO  BY  1 

UNTIL  RCODE  NOT  EQUAL  TO  OK. 


GET-NEXT. 

CALL  "GDPFLC"  USING  EXPFRM-NAME , 

TSTFLD-NAME , 
FIELD-NUM, 
DEPFLD-NAME , 
RCODE. 

IF  RCODE  IS  EQUAL  TO  OK 


ELSE 

CALL  " PMSGLC"  USING  RCODE. 
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4.15  GETATT 

The  foreground  attribute  for  items  (specified  during  form 
definition  with  the  DISPLAY  AS  clause),  can  be  changed  at  run-time 
using  the  routine  PUTATT.  Foreground  attributes  can  be  changed 
for  the  next  display  only  (temporary)  or  until  PUTATT  is  called 
again  (permanent).  This  routine  allows  you  to  find  out  the 
current  values  for  temporary  and  permanent  attributes. 

4.15.1  Calling  Format 

CALL  "GETATT"  USING  QUALIFIED-NAME, 

ATTRIBUTE-TYPE, 

ATTRIBUTE-ID, 

RCODE . 

4.15.2  Parameter  Descriptions 


NAME 

I/O 

FORMAT 

DESCRIPTION 

QUALIFIED- 

NAME 

Input 

Str 

( 1-120) 

The  qualified  name  of  the  Dis¬ 
play  List  element  that  identi¬ 
fies  the  item  whose  attribute 
you  want  to  know.  Refer  to 
Section  3. 

ATTRIBUTE- ! 
TYPE 

Input 

Num 

The  attribute  type  whose  value 
you  want  to  know.  The  include 
FPPARM  contains  the  definitions 
for  the  type  values  PERM  &  TEMP 

ATTRIBUTE- 

ID 

Output 

Str ( 10 ) 

The  attribute  value  defined  for 
the  specified  item  for  the  spe¬ 
cified  attribute  type.  If  a 
temporary  attribute  has  not 
been  defined  or  has  already 
been  displayed,  this  value  will 
be  blanks. 

RCODE 

Output 

i 

IT)  1 

U  1 

4->  1 

CO  1 

The  routine  return  code.  The 
possible  values  are  defined  in 
the  include  member  FPCODE. 

i - 

-  L 
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GETATT 


WORKING-STORAGE  SECTION. 

COPY  FPCODE  OF  IISSCLIB. 

COPY  FPPARM  OF  IISSCLIB. 

01  ITEM-PATH  PIC  X(12)  VALUE  " FORM1 . ITEM2 ; " . 

PROCEDURE  DIVISION. 


CALL  "GETATT"  USING  ITEM-PATH, 

PERM, 

ATTRIB-ID, 

RCODE . 

IF  RCODE  IS  EQUAL  TO  OK 


ELSE 

CALL  " PMSGLC"  USING  RCODE. 
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4 . 16  GETBAK 

This  routine  allows  you  to  find  out  the  current  values  for 
form  and  window  background  attributes.  The  background  attribute 
of  forms  and  windows  (specified  during  form  definition  with  the 
BACKGROUND  clause  or  with  the  routine  SETATT) ,  can  be  changed  at 
run-time  using  the  routine  PUTBAK.  Some  attributes  can  be  changed 
for  the  next  display  only  (temporary)  or  until  the  routine  PUTBAK 
is  called  again  (permanent) .  However,  temporary  is  not  supported 
at  this  time  and  an  attribute  value  remains  in  effect  for  all 
following  calls  to  OUTSCR  or  OISCR  until  PUTBAK  is  called  again. 

4.16.1  Calling  Format 

CALL  "GETBAK"  USING  QUALIFIED-NAME, 

BACKGROUND-TYPE , 

BACKGROUND-ID, 

RCODE . 

4.16.2  Parameter  Descriptions 

NAME  I/O  FORMAT  DESCRIPTION 


+ - 

QUALIFIED- 

NAME 

h - - 

Input 

h - 

Str 

(1-120) 

The  qualified  name  of  the  Dis-i 
play  List  element  that  identi¬ 
fies  the  form  or  window  whose 
background  you  want  to  know. 
Refer  to  Section  3.4. 

BACKGROUND- 

TYPE 

Input 

Num 

The  background  type  whose  val¬ 
ue  you  want  to  know.  The  in-  ; 
elude  member  contains  the  def-j 
inition  for  type  values  PERM  & 
TEMP.  TEMP  is  not  supported  at 
this  time. 

BACKGROUND- 

ID 

Output 

Str (10) 

The  background  value  defined  ! 
for  the  specified  form  or 
window. 

RCODE 

Output 

Str(5)  ! The  routine  return  code.  lhe 

1  possible  values  are  defined  in 
the  include  member  FPCODE. 

UM  620344 
" ''  September  1 


GETBAK 


WORKING-STORAGE  SECTION. 

COPY  FPCODE  OF  IISSCLIB. 

COPY  FPPARM  OF  IISSCLIB. 

01  BACK-ID  PIC  X(10)  . 

01  QUAL-NAME  PIC  X(ll)  VALUE  " FORM1 . WIN2 ; " . 

PROCEDURE  DIVISION. 


CALL  "GETBAK"  USING  QUAL-NAME, 

PERM, 

BACK-ID, 

RCODE . 

IF  RCODE  IS  EQUAL  TO  OK 


ELSE 

CALL  " PMSGLC"  USING  RCODE. 
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4.17  GETCUR 


This  routine  finds  the  current  cursor  position.  It  returns 
the  qualified  name  of  the  Display  List  element  in  which  the  cursor 
is  found  and  the  row  and  column  within  this  element.  The 
subscripts  (if  any)  of  an  array  in  which  it  lies  as  well  as  page 
numbers  are  included  in  the  fully  qualified  name.  In  applications 
that  have  menu  selection  by  cursor  position,  this  routine  is  used 
to  determine  the  user's  menu  choice. 

4.17.1  Calling  Format 

CALL  "GETCUR"  USING  QUALIFIED-NAME, 

FIELD-TYPE, 

ROW, 

COL, 

RCODE . 

4.17.2  Parameter  Descriptions 


NAME  I/O  FORMAT  DESCRIPTION 

QUALIFIED- 

NAME 

Input 

Str 

(1-120) 

i 

The  qualified  name  of  the  Dis¬ 
play  List  element  that  identi¬ 
fies  the  current  position  of 
the  cursor.  See  Section  3.4. 

FIELD-TYPE 

Input 

Num 

A  character  code  to  identify 
the  type  of  field  the  cursor 
was  found  in.  Values  are: 

F  -  form,  W  -  window,  and  I  - 
item . 

ROW 

Output 

Num 

The  row  position  of  the  cursor 
within  the  field  (i.e.  with 
respect  to  the  origin  of  the 
particular  field). 

COL 

Output 

h - 1 

Num 

r - H 

The  column  position  of  the 
cursor  within  the  field  (i.e. 
with  respect  to  the  origin  of 
the  particular  field). 
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RCODE 

Output 

Str (5) 

The  routine  return  code.  The 

possible  values  are  defined  in 
the  include  member  FPCODE. 

+ - + - - + - - - + 


4.17.3  Example 

WORKING-STORAGE  SECTION. 
COPY  FPCODE  OF  IISSCLIB. 
COPY  FPPARM  OF  IISSCLIB. 


01 

FULL-NAME 

PIC 

X  ( 12  0 )  . 

01 

TYPE  1 

PIC 

X. 

01 

ROW 

PIC 

S9(5) 

COMP. 

01 

COL 

PIC 

S9  ( 5 ) 

COMP. 

PROCEDURE  DIVISION. 


CALL  "GETCUR"  USING  FULL-NAME, 

TYPE1 , 

ROW, 

COL, 

RCODE . 

IF  PCODE  IS  EQUAL  TO  OK 


ELSE 

CALL  " PMSGLC"  USING  RCODE. 
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4 . 13  GETDQN 

This  routine  gets  the  fully  qualified  name  which  identifies 
the  current  default  field.  A  procedure  which  handled  a  form  might 
get  and  save  the  current  default  qualified  name,  set  the  default 
to  its  own  form  and  restore  the  previous  default  with  the  saved 
name  before  returning. 

4.18.1  Calling  Format 

CALL  "GETDQN"  USING  FULL-NAME, 

RCODE . 

4.18.2  Parameter  Descriptions 


- 1 

FULL-NAME 

h - - 

Output 

h - 1 

Str 

(120) 

The  absolute  fully  qualified 
name  that  identifies  the  de-  i 
fault  field  for  relative 
qualified  names. 

RCODE 

i  Output 

h - H 

Str (5) 

The  routine  return  code.  The 
possible  values  are  defined  in 
the  include  member  FPCODE. 

4.18.3  Example 

WORKING-STORAGE  SECTION. 

COPY  FPCODE  OF  IISSCLIB. 

COPY  FPPARM  OF  IISSCLIB. 

01  FULL-NAME  PIC  X(120). 

PROCEDURE  DIVISION. 


CALL  "GETDQN"  USING  FULL-NAME, 

RCODE. 

IF  RCODE  IS  EQUAL  TO  OK 


ELSE 

CALL  " PMSGLC"  USING  RCODE. 


GETLDV 
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4 . 19  GETLDV 

This  routine  gets  the  display  parameters  (row,  col,  width  and 
depth)  for  a  logical  device  belonging  to  an  application.  If  the 
logical  device  is  not  opened  GETLDV  will  return  an  NFPDSTRC  error. 

4.19.1  Calling  Format 

CALL  "GETLDV"  USING  LDWNID, 

DSPROW , 

DSPCOL , 

DSPWDTH , 

DSPDPTH , 

RCODE . 

4.19.2  Parameter  Description 

NAME  I/O  FORMAT  DESCRIPTION 

+ - + - + - + - + 


| LDWNID  | Input  | 

Num 

The  id  of  the  logical  device. 

DSPROW 

Output 

Num 

The  row  position  of  the  origin 
of  the  logical  device's  display 

DSPCOL 

Output 

Num 

1 

The  column  position  of  the 
origin  of  the  logical  device's 
display . 

DSPWDTH 

Output 

Num 

The  width  of  the  logical 
devices's  display. 

DSPDPTH 

Output 

Num 

The  depth  of  the  logical 
device's  display. 

RCODE 

-1 - —  —  — - -4 

Output 

L  —  —  —  - 

Str (5) 

i-  — 

The  routine  return  code.  The 
possible  values  are  defined  in 
the  include  member  FPCODE. 
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GETLDV 


4.19.3  Example 

WORKING_STORAGE  SECTION. 
COPY  FPCODE  OF  IISSCLIB. 
COPY  FPPARM  OF  IISSCLIB. 
PROCEDURE  DIVISION. 


CALL  "GETLDV"  USING  LDWNID, 

DSPROW, 
DSPCOL , 
DSPWDTH , 
DSPDPTH, 
RCODE . 

IF  RCODE  IS  EQUAL  TO  OK 


ELSE 

CALL  " PMSGLC"  USING  RCODE. 


GETVTI 
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4.20  GETVTI 


This  routine  gets  application  data  from  the  Virtual  Terminal. 
The  routine  INITVT  must  be  called  first  to  enable  VT  pass-through 
mode . 

4.20.1  Calling  Format 

CALL  "GETVTI"  USING  BUFFER, 

BUF-SIZE, 

LENGTH, 

CODE. 

4.20.2  Parameter  Descriptions 


NAME  I/O  FORMAT  DESCRIPTION 

BUFFER 

Output 

Str ( 1- 
BUF-SIZE) 

The  data  and  commands  received 
from  the  Virtual  Terminal. 

BUF-SIZE | Input  | Num 

'  | 

The  size  of  BUFFER.  | 

LENGTH 

Output 

Num 

The  actual  length  of  the  data 
and  commands  returned  in  BUFFER 

1 

i- 

RCODE 

Output 

Str (5) 

The  routine  return  code.  The 
possible  values  are  defined  in 
the  include  member  FPCODE. 

+ - 4- - + - + 
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4.20.3  Example 


WORKING-STORAGE 

SECTION. 

COPY 

FPCODE  OF 

IISSCLIB. 

COPY 

FPPARM  OF 

IISSCLIB. 

01 

VTI-BUF 

PIC  X(l) 

OCCURS  1  TO 

1000  TIMES 

DEPENDING 

ON  BUF-LEN. 

01 

BUF-SIZ 

PIC  S9 ( 5 ) 

COMP  VALUE 

1000  . 

01 

BUF-LEN 

PIC  S9(5) 

COMP. 

PROCEDURE  DIVISION. 


CALL  "INITVT"  USING  RCODE . 
IF  RCODE  IS  EQUAL  TO  OK 


CALL  "GETVTI"  USING  VTI-BUF, 
BUF-SIZ, 
BUF-LEN, 

RCODE 

IF  RCODE  IS  EQUAL  TO  OK 


ELSE 

CALL  " PMSGLC"  USING  RCODE 

ELSE 

CALL  "PMSGLC"  USING  RCODE. 
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4.21  GFMFLD 


This  routine  returns  the  name  and  type  of  a  field  on  a 
specified  form  based  on  the  order  fields  were  defined  on  the  form, 
To  return  this  information  for  all  fields  on  a  form,  this  routine 
should  be  called  in  a  loop  that  is  terminated  by  the  warning 
NOMORFLD.  In  order  to  determine  complete  dependencies,  if  the 
form  contains  form  fields,  their  field  information  should  also  be 
obtained . 


4.21.1  Calling  Format 

CALL  "GFMFLD"  USING 


FORM-NAME, 
FIELD-NUM, 
FIELD-NAME, 
FIELD-TYPE, 
RCODE . 


4.21.2  Parameter  Descriptions 


NAME 

I/O 

FORM-NAME 

Input 

FIELD-NUM  | 

I  Input 

FORMAT  DESCRIPTION 

+ - - ^ - - - - - 

Str(10) j The  name  of  the  form  whose 
I  field  names  you  want. 


Num 


A  number  based  or  the  order 
fields  were  defined  on  the  form 
to  indicate  the  field  whose 
name  you  want  (i.e.  a  positive 
number  of  1  or  more  refers  to 
the  actual  order  the  fields 
were  defined  in.  0  refers  to 
the  most  recently  defined  field 
and  a  negative  number  of  1  or 
more  refers  to  the  reverse 
order  the  fields  were  defined 
starting  with  the  next  most 
recently  added. 


-  +  - 


FIELD-NAME 


Output 


Str ( 10) 


The  name  of  the  field  referred 
to  by  the  specified  FIELD-NAME. 
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+ - + - + - + - + 


FIELD-TYPE 

Output 

Str(l) 

A  character 
the  type  of 
is.  Values 
window,  and 

code  to  identify 
field  FIELD-NAME 
are:  F  -  form,  W  - 

I  -  item. 

RCODE 

Output 

Str (5) 

The  routine  return  code.  The 
possible  values  are  defined  in 
the  include  member  FPCODE. 

+ - + - + - + - + 


4.21.3  Example 


WORKING-STORAGE  SECTION. 
COPY  FPCODE  OF  IISSCLIB. 
COPY  FPPARM  OF  IISSCLIB. 


01 

EXPFRM-NAME 

PIC 

X(10)  VALUE 

01 

FIELD-NUM 

PIC 

S9 ( 5 )  COMP. 

01 

FIELD-NAME 

PIC 

x ( 10) . 

01 

FIELD-TYPE 

PIC 

X(l)  . 

PROCEDURE  DIVISION. 

"EXPFRM" . 


PERFORM  GET-NEXT  VARYING  FI ELD-NUM  FROM  ZERO  BY  1 

UNTIL  RCODE  NOT  EQUAL  TO  OK. 


GET-NEXT. 

CALL  "GFMFLD"  USING  EXPFRM-NAME , 

FI ELD-NUM , 

FIELD-NAME, 

FIELD-TYPE, 

RCODE. 

IF  RCODE  IS  EQUAL  TO  OK 


ELSE 

CALL  " PMSGLC"  USING  RCODE. 


GPAGE 


I'M  0  2  (j 
>0  Geptembe 


4.22  GPAGE 


This  routine  finds  the  name  c:  the  form  that  a  specif ie 
of  a  window  currently  contains.  The  routine  GWINDO  may  be  c 
to  find  out  hov;  many  pages  are  currently  contained  in  a  wind 
This  information  ^s  used  to  determine  qualified  names  in  the 
current  Display  List. 

4.22.1  Calling  Format 

CALL  "GPAGE"  USING  QIJ  A  L.  I F I E  D  -  W I N  DOW  -  N  AM  E  , 

PAGE -NUMBER, 

FORM -NAME, 

RCODE . 

4.22.2  Parameter  Descript  ions 


NAME  I/O  FORMAT  DESCRIPTION 


- _l 

QUALIFIED- 
WINDOW  - 
NAME 

p - h 

Input 

! 

Str  |  The  qualified  name  of  the  •rin- 

(1-120)  j dow  whose  contents  you  are 
j identifying. 

PAGE- 

NUMBER 

: 

Input 

Nun  The  page  of  the  window  that 

! contains  the  form  you  are  iden- 
!  t.  i  f  y  ing  . 

FORM-NAME  1 

Output 

Str(10)  The  name  of  the  form  that  the 
: specified  page  of  the  window 
!  conta  i.  ns  . 

RCODF 

Output  St r ( 5 )  ; The  routine  return  code.  The 

'possible  values  are  defined  in 
j  .the  include  member  FPCODE. 

GPAGE 


4.22.3  Example 

WORKING-STORAGE  SECTION. 

COPY  FPCODE  OF  IISSCLIB. 

COPY  FPPARM  OF  IISSCLIB. 

01  EXPFRM-NAME  PIC  X(10). 

01  CURPAG  PIC  S9 ( 5 )  COMP  VALUE  2. 

PROCEDURE  DIVISION. 


CALL  "GPAGE"  USING  SCREN, 

CURPAG, 
EXPFRM-NAME, 
RCODE . 

IF  RCODE  IS  EQUAL  TO  OK 


ELSE 

CALL  " PMSGLC"  USING  RCODE. 


GTU INF 
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4.23  GTUINF 


This  routine  returns  the  values  that  were  in  the  User  ID  and 
Role  fields  on  the  IISS  Function  Screen  when  the  application 
began.  This  information  may  be  used  to  control  the  application. 
For  example  to  access  a  shared  data  base  you  could  select  the  data 
in  the  data  base  using  the  user's  name.  The  user's  role  can  be 
used  to  allow  different  users  access  to  a  selected  group  of 
functions . 

4.23.1  Calling  Format 

CALL  "GTUINF"  USING  USRNAM , 

US ROLE , 

RCODE . 

4.23.2  Parameter  Descriptions 

NAME  I/O  FORMAT  DESCRIPTION 


- + - H 

USRNAM  | Output | 

Str ( 10) | User ' s  Name 

USROLE  j 

Output | Str ( 10)  j User ' s  Role 

RCODE 

Output 

Str (5) 

: 

h - - 

The  routine  return  code.  The 
possible  values  are  defined  in 
the  include  member  FPCODE. 

+ 
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4.23.3  Example 

WORKING-STORAGE  SECTION. 

COPY  FPCODE  OF  IISSCLIB. 

COPY  FPPARM  OF  IISSCLIB. 

01  USRNAM  PIC  X(10) 

01  USROLE  PIC  X(10) 

PROCEDURE  DIVISION. 


CALL  "GTUINF"  USING  USRNAM, 

USROLE, 

RCODE . 

IF  RCODE  IS  EQUAL  TO  OK 


ELSE 

CALL  " PMSGLC"  USING  RCODE. 


GTUSYM 
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4.24  GTUSYM 


This  routine  returns  the  prototype  strings  for  the  location 
of  the  source  and  compiled  forms  (IISSSLIB  and  IISSULIB)  as 
defined  in  the  UI  Database  for  the  logged  on  user. 

4.24.1  Calling  Format 

CALL  "GTUSYM"  USING  SLIB, 

ULIB, 

RCODE . 

4.24.2  Parameter  Descriptions 

NAME  I/O  FORMAT  DESCRIPTION 


- H 

SLIB 

h - H 

Output 

h - -i 

Str (80) 

The  prototype  string  for  the 
form  source  file. 

ULIB 

Output 

Str (80) 

The  prototype  string  for  the 
compiled  form  file. 

RCODE 

Output 

i - 

Str (5) 

(- - 

The  routine  return  code.  The 
possible  values  are  defined  in 
the  include  member  FPCODE. 

4.24.3  Example 

WORKING-STORAGE  SECTION. 

COPY  FPCODE  OF  IISSCLIB. 

COPY  FPPARM  OF  IISSCLIB. 

01  SLIB  PIC  X ( 3 0 ) 

01  ULIB  PIC  X ( 8 0 ) 

PROCEDURE  DIVISION. 


CALL  "GTUSYM"  USING  SLIB, 

ULIB, 

RCODE. 

IF  RCODE  IS  EQUAL.  TO  OK 


ELSE 

CALL  " PMSGI.C"  USING  RCODE. 
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4 .25  GWINDO 

This  routine  lets  you  find  how  many  pages  a  window  currently 
contains.  The  routine  GPAGE  can  then  be  called  to  find  the  name 
of  the  form  contained  in  a  page.  This  information  is  used  to 
determine  qualified  names  of  elements  in  the  current  Display  List. 

4.25.1  Calling  Format 

CALL  "GWINDO"  USING  QUALIFIED-WINDOW-NAME, 

TOTAL-PAGES , 

RCODE . 

4.25.2  Parameter  Descriptions 

NAME  I/O  FORMAT  DESCRIPTION 


- -1 

QUALIFIED- 

WINDOW- 

NAME 

b - H 

Input 

b - 1 

Str 

(1-120) 

i 

The  qualified  name  of  the  Dis¬ 
play  List  element  that  identi¬ 
fies  the  window  whose  page 
count  you  want. 

TOTAL- 

PAGES 

Output 

Num 

The  total  number  of  pages  the 
specified  window  currently 
contains. 

RCODE 

Output 

b - H 

Str (5) 

The  routine  return  code.  The 
possible  values  are  defined  in 
the  include  member  FPCODE. 

UM  620344 2 uu 
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GW IN DO 


WORKING-STORAGE  SECTION. 

COPY  FPCODE  OF  IISSCLIB. 

COPY  FPPARM  OF  IISSCLIB. 

01  TOTAL-PAGES  PIC  S9(5)  COMP. 
PROCEDURE  DIVISION. 

CALL  "GWINDO"  USING  SCREN, 

TOTAL-PAGES , 

RCODE . 

IF  RCODE  IS  EQUAL  TO  OK 


ELSE 

CALL  " PMSGLC"  USING  RCODE. 


4-50 


INITFP 


UM  G  2  0  3  4  4  2  0  (J 
30  September  10'n> 


4 • 26  INITFP 

This  routine  is  used  to  initialize  the  Form  Processor.  This 
includes  creating  a  logical  device  which  consists  of  a  Display 
List  beginning  with  the  form  PSCREN.  INITFP  must  be  called  prior 
to  any  other  FP  routiner . 

4.26.1  Calling  Format 
CALL  "INITFP". 

4.26.2  Parameter  Descriptions 
NONE. 

4.26.3  Example 

WORKING-STORAGE  SECTION. 

PROCEDURE  DIVISION. 

CALL  "INITFP". 
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INI T VT 


4 . 27  INITVT 

This  routine  sets  the  VT  pass-through  mode  which  provides 
direct  access  to  the  Virtual  Terminal  without  using  the  Form 
Processor.  The  routines  GETVTI  and  PUTVTI  are  then  used  to 
receive  and  transmit  data.  This  mode  is  primarily  for  system  code 
and  should  not  be  used  in  user  applications. 

4.27.1  Calling  Format 

CALL  "INITVT"  USING  RCODE. 


4.27.2  Parameter  Descriptions 
NAME 


I/O 


FORMAT  DESCRIPTION 


■  +  - 


RCODE 


Output 


Str  (  5) 


The  routine  return  code.  The  j 
possible  values  are  defined  in 
the  include  member  FPCODE. 


4.27.3  Example 

WORKING-STORAGE  SECTION. 
COPY  FPCODE  OF  IISSCLIB. 
COPY  FPPARM  OF  IISSCLIB. 
PROCEDURE  DIVISION. 


CALL  "INITVT"  USING  RCODE. 
IF  RCODE  IS  EQUAL  TO  OK 


ELSE 

CALL  "PMSGLC"  USING  RCODE. 
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4.28  INQABS 


This  routine  returns  the  absolute  row  and  column  of  a  field'; 
position  relative  to  its  containing  form  after  resolving  relative 
positions . 

4.28.1  Calling  Format 

CALL  "INQABS"  USING  FORM-NAME, 

FIELD-NAME, 

ROW, 

COL, 

RCODE . 

4.28.2  Parameter  Descriptions 


NAME 

I/O  FORMAT 

DESCRIPTION 

FORM-NAME 

| Input  | Str ( 10) 

| The  name  of  the  containing  form 

FIELD-NAME 

:  Input  |str(i0) 

The  name  of  the  field  whose 
absolute  location  you  want. 

ROW 

Output  Num 

The  absolute  row  of  the  field 
location . 

COL 

j  Output  Num 

The  absolute  column  of  the 
field  location. 

RCODE 

I  Output  1 Str ( 5 ) 

1  The  routine  return  code.  The 

possible  values  are  defined  in 
the  include  member  FPCODE. 


INQABS 
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WORKING-STORAGE  SECTION. 
COPY  FPCODE  OF  IISSCLIB. 
COPY  FPPARM  OF  IISSCLIB. 


01 

EXPFRM-NAME 

PIC 

X(10) 

VALUE  "EXPFRM" . 

01 

TSTFLD-NAME 

PIC 

X(10) 

VALUE  "TSTFLD" . 

01 

TSTFLD-ROW 

PIC 

S9  (  5 ) 

COMP. 

01 

TSTFLD-COL 

PIC 

S9  ( 5 ) 

COMP. 

PROCEDURE  DIVISION. 


CALL  "INQABS"  USING  EXPFRM-NAME, 

TSTFLD-NAME, 

TSTFLD-ROW, 

TSTFLD-COL, 

RCODE . 

IF  RCODE  IS  EQUAL  TO  OK 


ELSE 

CALL  "PMSGLC"  USING  RCODE. 


4-54 


UM  62 034 4  2 UO 
3  0  September  ! 


INQAPR 


4.29  INQAPR 

,7,l.is  routine  returns  the  criterion  defined  to  determine  when 
the  specified  field  appears  on  its  containing  form.  The  CRITERION 
parameter  corresponds  to  the  Criterion  component  of  the  APPEARS  IF 
clause  syntax  described  in  the  Form  Editor  User's  Manual. 

4.29.1  Calling  Format 

CALL  "INQAPR"  USING  FORM-NAME, 

FIELD-NAME, 

BUF-SIZE, 

CRITERION, 

LENGTH, 

RCODE . 

4.29.2  Parameter  Descriptions 

NAME  I/O  FORMAT  DESCRIPTION 


H - + - -I 

|  FORM-NAME  | Input  | 

Str(10) | The  name  of  the  containing  form 

FIELD-NAME 

Input 

Str(10) 

The  name  of  the  field  whose 
appears  if  criterion  you  want. 

BUF-SIZE 

Input 

Num 

The  length  of  the  buffer  being 
reserved  for  the  criterion. 

CRITERION 

Output 1 

Str 

(BUF- 

SIZE) 

The  appears  if  criterion  de¬ 
fined  for  the  field  either 
padded  with  spaces  or  truncated 

LENGTH 

Output 

Num 

The  actual  length  of  the  cri¬ 
terion  without  padding.  Also 
the  minimum  buffer  length 
needed  to  receive  a  non-trun- 
cated  criterion.  Comparing  BUF- 
SIZE  and  LENGTH  determines  if 
CRITERION  is  truncated. 

j  RCODE 

1  Output 

Str (5) 

j The  routine  return  code.  The 

possible  values  are  defined  in  | 
the  include  member  FPCODE. 


+ - h - ^ - + 
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This  routine  may  first  be  called  with  a  BUF-SIZE  of 
This  forces  an  error  but  LENGTH  will  be  the  actual  buffer 
needed  to  store  the  appears  if  criterion. 


4.29.3  Example 


WORKING-STORAGE  SECTION. 
COP/  FPCODE  OF  IISSCLIB. 
FPPARM  OF  IISSCLIB. 


COPY 

01 

01 

01 

01 

01 


EXPFRM-NAME  PIC 
TSTFLD-NAME  PIC 
BUF-SIZE  PIC 
CRIT-BUF  PIC 
BUF-LEN  PIC 


PROCEDURE  DIVISION . 


X(10)  VALUE 
X(10)  VALUE 
S9 ( 5 )  COMP 
X(100)  . 

S9 ( 5 )  COMP. 


"EXPFRM" 
"TSTFLD" 
VALUE  100 


CALL  "  INQAPR1,  USING  EXPFRM-NAME, 

TSTFLD-NAME, 

BUF-SIZE, 

CRIT-BUF, 

BUF-LEN, 

P.CODE  . 

IF  RCODE  IS  EQUAL  TO  OK 


ELSE 

CALL  "PMSGLC"  USING  RCODE. 


zero . 
size 
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4.30  INQATT 


This  routine  returns  either  an  attribute  name  or  the 
primitive  values  for  a  specified  form  attribute.  The  routine 
parameters  correspond  to  the  components  of  the  ATTRIBUTE  clause 
syntax  described  in  the  Form  Editor  User's  Manual. 

4.30.1  Calling  Format 

CALL  "INQATT"  USING  FORM-NAME, 

ATTRIBUTE-ID, 

ATTR-TYPE, 

INDEX, 

ATTRIBUTE, 

RCODE . 


NAME 

I/O 

FORMAT 

DESCRIPTION 

FORM-NAME 

Input 

Str(10) 

! 

The  name  of  the  form  whose  at¬ 
tribute  information  you  want. 

ATTRIBUTE- 

ID 

Input 

Str ( 10) 

The  name  of  the  attribute  whose 
primitives  you  want  or  blank  to 
indicate  that  you  want  the  name 
of  the  attribute  specified  by 
the  INDEX  value. 

ATTR-TYPE 

- H 

Input 

1 - H 

Str(l) 

- - H 

A  character  code  to  identify 
which  type  of  primitive  you 
want.  Values  are:  D  -  display 
color,  B  -  background  color,  & 

P  -  other  primitives,  such  as 
hidden,  guarded,  etc.  ATTR-TYPE 
shuld  be  blank  if  ATTRIBUTE-ID 
is  blank. 
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t- - H 

INDEX 

h - H 

Input 

h - H 

Num 

An  index  number  to  specify  pos¬ 
ition  in  a  list.  If  ATTRIBUTE- 
ID  is  blank,  this  is  the  list 
of  all  attributes  defined  for 
the  form.  If  ATTRIBUTE-ID  is 
not  blank,  this  is  the  list  of 
primitives  for  the  specified 
attribute.  INDEX  is  ignored 
the  ATTR-TYPE  value  is  "B"  or 
"D" . 

ATTRIBUTE 

Output 

Str(10) 

The  name  of  the  attribute  if 
ATTRIBUTE-ID  is  blank  or  the 
attribute  primitive  (or  color 
if  ATTRIBUTE-ID  is  not  blank) . 
The  string  is  non-null  termin¬ 
ated  and  padded  with  blanks  as 
needed . 

RCODE 

f - 

Output 

— 

Str (5) 

- j 

The  routine  return  code.  The 
possible  values  are  defined  in 
the  include  member  FPCODE. 

4.28.3  Example 

WORKING-STORAGE  SECTION. 
COPY  FPCODE  OF  IISSCLIB. 
COPY  FPPARM  OF  IISSCLIB. 


01 

EXPFRM-NAME 

PIC 

X(10) 

VALUE  "EXPFRM". 

01 

TSTATR-NAME 

PIC 

X(10) 

VALUE  "TESTATTR" 

01 

DISP-TYPE 

PIC 

X  VALUE  "D". 

01 

DUMMY 

PIC 

S9  ( 5 ) 

COMP. 

01 

DISP-COLOR 

PIC 

X(10) 

. 

PROCEDURE  DIVISION. 
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INQATT 


CALL  "INQATT"  USING  EXPFRM-NAME, 

TSTATR-NAME, 

DISP-TYPE, 

DUMMY, 

DISP-COLOR, 

RCODE . 

IF  RCODE  IS  EQUAL  TO  OK 


ELSE 

CALL  " PMSGLC"  USING  RCODE. 
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4.31  INQDIM 


This  routine  returns  information  about  a  field's  array 
dimensions. 

4.31.1  Calling  Format 

CALL  "INQDIM"  USING  FORM-NAME, 

FIELD-NAME, 

INDEX, 

DISPLAY-SIZ, 

ACTUAL-SIZ , 

DIRECTION, 

SPACES, 

RCODE . 


NAME 

I/O 

FORMAT 

DEFINITION 

FORM-NAME  | 

Input 

Str(10) 

The  name  of  the  containing  form 

FIELD-NAME 

Input  | 

°  "r  ( 1 0 ) 

The  name  of  the  field  whose 
array  dimension  information  you 
want . 

INDEX 

Input 

Num 

A  number  to  indicate  which  ar¬ 
ray  dimension  information  you 
want . 

DISPLAY- 

SIZE 

Output 

Num 

The  number  of  field  repetitions 
to  display  on  the  form.  Zero  is 
returned  for  open-ended  arrays. 

ACTUAL- 

SIZE 

Output 

Num 

The  total  number  of  times  the 
field  actually  repeats.  Zero  is 
returned  for  open-ended  arrays. 

DIRECTION 

|  Output 1 

1  Str ( 1) 

The  direction  (H  or  V)  of  the 

the  repeat. 
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+  — — —  —————  — — +  —  —  — - 1 - 1 - —  —  — -  - —  —  — - 1- 


SPACES 

Output 

Num 

The  number  of  spaces  between 
elements . 

RCODE 

1 

+ - H 

Output 

1 

h - H 

Str (5) 

r - - 

The  routine  return  code.  The 
possible  values  are  defined  in 
the  include  member  FPCODE. 

4.31.3  Example 


WORKING-STORAGE  SECTION. 
COPY  FPCODE  OF  IISSCLIB. 
COPY  FPPARM  OF  IISSCLIB. 


01 

EXPFRM-NAME 

PIC 

X(10) 

VALUE  "EXPFRM 

01 

TSTFLD-NAME 

PIC 

X(10) 

VALUE  "TSTFLD 

01 

TSTFLD-DIM 

PIC 

S9  ( 5 ) 

COMP  VALUE  1. 

01 

DSP-SIZE 

PIC 

S9  ( 5 ) 

COMP. 

01 

ACT-SIZE 

PIC 

S9(5) 

COMP. 

01 

NUM-SPACES 

PIC 

S9  ( 5 ) 

COMP. 

01 

RPT-DIRECTION 

PIC 

X. 

PROCEDURE  DIVISION. 


CALL  "INQDIM"  USING  EXPFRM-NAME, 

TSTFLD-NAME , 
TSTFLD-DIM, 
DSP-SIZE , 
ACT-SIZE, 
NUM-SPACES, 

RPT- DIRECTION , 
RCODE . 

IF  RCODE  IS  EQUAL  TO  OK 


ELSE 

CALL  "PMSGLC"  USING  RCODE. 
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4.32  INQDIS 


This  routine  returns  the  permanent  attribute  of  a  form  or 
field.  The  permanent  attribute  corresponds  to  the  attribute_id 
component  in  the  BACKGROUND  clause  syntax  for  forms  and  window 
fields  and  in  the  DISPLAY  AS  clause  syntax  for  item  fields  as 
described  in  the  Form  Editor  User's  Manual. 

4.32.1  Calling  Format 

CALL  "INQDIS"  USING  FORM-NAME, 

FIELD-NAME, 

PERM-ATTR , 

RCODE . 


NAME 

I/O 

FORMAT 

DESCRIPTION 

FORM-NAME 

Input 

Str(10) 

The  name  of  the  form  whose  at¬ 
tribute  you  want  or  that  con¬ 
tains  the  field  whose  attribute 
you  want. 

FIELD-NAME 

Input 

Str ( 10) 

The  name  of  the  field  whose  at¬ 
tribute  you  want  or  blank  if 
you  want  the  attribute  of  FORM- 
NAME. 

PERM-ATTR 

Output 

Str(10) 

The  name  of  the  form  or  field 
permanent  attribute. 

RCODE 

Output 

Str (5) 

The  routine  return  code.  The 
possible  values  are  defined  in 
the  include  member  FPCODE. 
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4.32.3  Example 

WORKING-STORAGE  SECTION. 
COPY  FPCODE  FROM  IISSCLIB. 
COPY  FPPARM  FROM  IISSCLIB. 


01 

EXPFRM-NAME 

PIC 

X(10) 

VALUE  "EXPFRM" . 

01 

TSTFLD-NAME 

PIC 

X  ( 10) 

VALUE  "TSTFLD" . 

01 

ATTR-NAME 

PIC 

X(10) 

• 

PROCEDURE  DIVISION. 


CALL  "INQDIS"  USING  EXPFRM-NAME , 

TSTFLD-NAME , 
ATTR-NAME, 

RCODE . 

IF  RCODE  IS  EQUAL  TO  OK 


ELSE 

CALL  " PMSGLC"  USING  RCODE. 


INQDOM 
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4 .33  INQDOM 

This  routine  returns  an  item  field's  domain  values.  These 
values  correspond  to  the  options  of  the  DOMAIN  clause  syntax 
described  in  the  Form  Editor  User's  Manual.  The  user  can  request 
a  specific  domain  value  or  all  the  domain  values  defined  for  the 
item  with  the  values  separated  by  commas. 

4.33.1  Calling  Format 

CALL  "INQDOM"  USING  FORM-NAME, 

ITEM-NAME, 

INDEX, 

BUF-SIZE, 

DOMAIN, 

LENGTH, 

RCODE . 

4.33.2  Parameter  Descriptions 

NAME  I/O  FORMAT  DESCRIPTION 


+ - + - + - + - + 


| FORM-NAME 

Input  | Str (10) 

The  name  of  the  containing  form 

ITEM-NAME 

Input 

Str (10) 

The  name  of  the  item  field 
whose  domain  values  you  want. 

INDEX 

Input 

Num 

A  number  to  indicate  which 
domain  value  you  want.  An  INDEX 
follows  the  parameter  descrip¬ 
tions  . 

BUF-SIZE 

Input 

Num 

The  size  of  the  buffer  being 
reserved  for  the  domain  value. 

DOMAIN 

+ - 

Output 

i- - 

Str 

(BUF- 

SIZE) 

h - 

The  domain  value  or  values, 
either  padded  with  spaces  or 
truncated . 

y- - + 
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- H 

LENGTH 

- - H 

Output 

i - 1 

Num 

The  actual  length  of  the  DOMAIN 
clause  without  padding.  This  is 
also  the  minimum  buffer  length 
needed  to  receive  a  non-trun- 
cated  domain  clause.  Comparing 
LENGTH  with  BUF-SIZE  determines 
whether  DOMAIN  contains  a  trun¬ 
cated  or  padded  value. 

RCODE 

- H 

Output 

b - H 

Str (5) 

L - H 

The  routine  return  code.  The 
possible  values  are  defined  in 
the  include  member  FPCODE. 

INDEX 


1  LEFT, RIGHT,  MUST  FILL  or  error 

2  UPPER,  LOWER  or  error 

3  NUMERIC  or  error 

4  MUST  ENTER  or  error 

5  MINIMUM  int  or  error 

6  MAXIMUM  int  or  error 

7  all  separated  by  commas 


For  INDEX  7,  this  routine  may  first  be  called  with  a  BUF-S1ZE 
of  zero.  This  causes  an  error  but  the  value  returned  in  LENGTH 
will  be  the  actual  buffer  size  needed  to  store  all  the  domain 
values . 


WORKING-STORAGE  SECTION. 
COPY  FPCODE  OF  IISSCLIB. 
COPY  FPPARM  OF  IISSCLIB. 


01 

EXPFRM-NAME 

PIC 

X(10) 

VALUE 

"EXPFRM" . 

01 

TSTFLD-NAME 

PIC 

X(10) 

VALUE 

"TSTFLD" . 

01 

ALLDOM-INDEX 

PIC 

S9  ( 5 ) 

COMP 

VALUE  7 . 

01 

BUF-SIZE 

PIC 

S9(5) 

COMP 

VALUE  200. 

01 

DOMAIN-BUF 

PIC 

X  OCCURS  1 

TO  200  TIMES 

DEPENDING 

ON  DOMAIN-LEN. 

01 

DOMAIN-LEN 

PIC 

S  9  (  5 ) 

COMP. 
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PROCEDURE  DIVISION. 


CALL  "INQDOM"  USING  EXPFRM-NAME, 

TSTFLD-NAME, 
ALLDOM-INDEX, 
BUF-SIZE, 
DOMAIN-BUF , 
DOMAIN-LEN, 

RCODE . 

IF  RCODE  IS  EQUAL  TO  OK 


ELSE 

CALL  "PMSGLC"  USING  RCODE. 
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4 . 34  INQHLP 

This  routine  returns  the  help  information  defined  for  an  item 
field.  The  output  parameters  correspond  to  the  components  of  the 
HELP  clause  syntax  described  in  the  Form  Editor  User's  Manual. 

4.34.1  Calling  Format 

CALL  "INQHLP"  USING  FORM-NAME, 

ITEM-NAME, 

TYPE, 

HELP, 

RCODE . 

4.34.2  Parameter  Descriptions 

NAME  I/O  FORMAT  DESCRIPTION 

+ - + - + - + - + 


| FORM-NAME  | 

Input  j 

Str(10) | The  name  of  the  containing  form| 

ITEM-NAME 

Input 

Str(10) 

The  name  of  the  item  field 
whose  help  information  you  want 

TYPE 

Input 

Str(l) 

A  character  code  to  identify 
the  type  of  help  that  is  de¬ 
fined.  Values  are  S-  string, 

A  -  application,  and  F  -  form. 

HELP 

Output 

Str (60) 

The  help  information  defined 
for  the  item  field.  Contents 
depend  on  the  TYPE  field.  For  F 
HELP  is  the  name  of  the  help 
form,  for  A  it  is  the  word  "AP¬ 
PLICATION",  and  for  S  it  is  the 
actual  help  text. 

] RCODE 

1  Output 

1  Str  ( 5) 

1  The  routine  return  code.  The 

possible  values  are  defined  in 
the  include  member  FPCODE. 


+ - 4- - + - + - + 
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WORKING-STORAGE  SECTION. 
COPY  FPCODE  OF  IISSCLIB. 
COPY  FPPARM  OF  IISSCLIB. 


01 

EXPFRM-NAME 

PIC 

X(10) 

VALUE  "EXPFRM" . 

01 

TSTFLD-NAME 

PIC 

X(10) 

VALUE  "TSTFLD" . 

01 

HELP-TYPE 

PIC 

X. 

01 

HELP-MSG 

PIC 

X  ( 60 ) 

PROCEDURE  DIVISION. 

CALL  "INQHLP"  USING  EXPFRM-NAME , 

TSTFLD-NAME, 

HELP-TYPE, 

HELP-MSG, 

RCODE . 

IF  RCODE  IS  EQUAL  TO  OK 


ELSE 

CALL  " PMSGLC"  USING  RCODE. 
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4 .35  INQLDV 

This  routine  is  used  to  retrieve  the  logical  device 
associated  with  the  current  Display  List.  NOTE:  The  id  of  the 
logical  device  that  is  assigned  to  an  application  when  INITFP  is 
called  can  only  be  retrieved  by  calling  this  routine.  If  the 
application  uses  multiple  logical  devices,  it  should  call  INQLDV 
before  changing  logical  devices  so  that  the  original  logical 
device  can  be  used  again. 

4.35.1  Calling  Format 

CALL  "INQLDV"  USING  LOGICAL-DEVICE-ID, 

RCODE . 

4.35.2  Parameter  Descriptions 

NAME  I/O  FORMAT  DESCRIPTION 

+ - + - + - + - + 


IOGICAL- 

DEVICE-ID 

Output 

Num 

The  id  of  the  logical  device 
that  the  application  is  using 
for  its  current  Display  List. 

RCODE 

: 

+ - H 

Output 

b - H 

Str (5) 

b - H 

The  routine  return  code.  The 
possible  values  are  defined  in 
the  include  member  FPCODE. 

4.35.3  Example 

WORKING-STORAGE  SECTION. 

COPY  FPCODE  OF  IISSCLIB. 

COPY  FPPARM  OF  IISSCLIB. 

01  LOGICAL-DEVICE-ID  PIC  S9(5)  COMP. 
PROCEDURE  DIVISION. 


CALL  "INQLDV"  USING  LOGICAL-DEVICE-ID, 

RCODE. 

IF  RCODE  IS  EQUAL  TO  OK 


ELSE 

CALL  " PMSGLC"  USING  RCODE. 


4-69 


INQLOC 


UM  620341200 
30  September  1990 


4.36  INQLOC 

This  routine  returns  the  relative  position  information  of  a 
form  or  field.  The  output  parameters  correspond  to  the  components 
of  the  Location  syntax  described  in  the  Form  Editor  User's  Manual. 

4.36.1  Calling  Format 

CALL  "INQLOC"  USING  FORM-NAME, 

FIELD-NAME, 

VREL-FIELD , 

VEXTREF, 

VINTREF, 

ROW, 

HREL-FIELD, 

HEXTREF, 

HINTREF, 

COLUMN, 

RCODE . 

4.36.2  Parameter  Descriptions 

NAME  I/O  FORMAT  DEFINITION 

+ - —  —  — f- - f  — - f  — - - - — - — - h 


FORM-NAME 

Input 

Str(10) 

The  name  of  the  containing  form 
or  the  name  of  the  form  whose 
|  position  information  you  want. 

FIELD-NAME 

Input 

Str ( 10) 

The  name 
position 
or  blank 
position 
NAME. 

of  the  field  whose 
information  you  want 
if  you  want  the 
information  for  FORM- 

+  “  “  ~  +  —  —  — - —  4-  — .  —  —  —  — - —  —  —  —  — - —  —  —  —  —  — - —  —  —  —  —  —  —  —  _j_ 
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+ - + - + - + - + 


VREL- 

FIELD 

Output 

Str 

(120) 

The  qualified  name  of  the  field 
that  the  form  or  field  position 
is  vertically  relative  to  or 
blank  if  it  is  relative  to  its 
containing  form. 

VEXTREF 

Output 

Num 

The  vertical  reference  point 
on  VREL-FIELD  that  the  form  or 
field  location  is  relative  to. 
Values  are  1  -  top,  2  -  center, 
3  -  bottom. 

VINTREF 

Output 

Num 

The  vertical  reference  point  of 
FIELD-NAME  or  FORM-NAME  that 
the  position  is  relative  to. 
Values  same  as  for  VEXTREF. 

ROW 

! 

Output 

Num 

The  number  of  rows  the  field  or 
form  is  offset  from  VREL-FIELDs 
reference  point. 

H - h - + - + - + 


HREL- 

FIELD 

Output 

1 

Str 

(120) 

The  qualified  name  of  the  field 
the  form  or  field  position  is 
horizontally  relative  to  or 
blank  if  it  is  relative  to  the 
containing  form. 

HEXTREF 

Output 

Num 

The  horizontal  reference  point 
of  the  field  the  form  or  field 
location  is  relative  to.  Values 
are:  1  -  left,  2  -  center,  and 

3  -  right. 

+ 


-t- 


+ 


+ 


+ 


HINTREF 

Output 

Num 

The  horizontal  reference  point 
of  FIELD-NAME  or  FORM-NAME  that 
the  position  is  relative  to. 
Values  the  same  as  for  HEXTREF. 

COLUMN 

! 

Output 

Num 

The  number  of  columns  the  field 
or  form  is  offset  from  HREL- 
FIELD's  reference  point. 

+ - + - 4- - + - + 
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+ - + - + - + - + 


RCODE 

Output 

Str (5) 

The  routine  return  code.  The 

possible  values  are  defined  in 
the  include  member  FPCODE. 

+ - + - + - + - + 


4.36.3  Example 


WORKING-STORAGE  SECTION. 
COPY  FPCODE  OF  IISSCLIB. 
COPY  FPPARM  OF  IISSCLIB. 
01  EXPFRM-NAME 

01  TSTFLD-NAME 

01  VREL-FIELD 

01  VEXTREF  PIC  S9(5) 

01  VINTREF  PIC  S9 ( 5 ) 

01  ROW  PIC  S9 ( 5 ) 

01  HREL-FIELD 

01  HEXTREF  PIC  S9(5) 

01  HINTREF  PIC  S9(5) 

01  COLUMN  PIC  S9 ( 5 ) 

PROCEDURE  DIVISION. 


PIC  X(10)  VALUE  "EXPFRM" 
PIC  X(10)  VALUE  "TSTFLD" 
PIC  X (120)  . 

COMP. 

COMP. 

COMP. 

PIC  X ( 12 0 )  . 

COMP. 

COMP. 

COMP. 


CALL  "INQLOC"  USING  EXPFRM-NAME, 
TSTFLD-NAME, 
VREL-FIELD, 

VEXTREF, 

VINTREF, 

ROW, 

HREL-FIELD, 

HEXTREF, 

HINTREF, 

COLUMN, 

RCODE . 

IF  RCODE  IS  EQUAL  TO  OK 


ELSE 

CALL  "PMSGLC"  USING  RCODE. 
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4 . 37  INQPRO 

This  routine  returns  form  or  field  prompt  information.  The 
output  parameters  that  return  position  information  correspond  to 
the  components  of  the  Location  syntax  described  in  the  Form  Editor- 
User's  Manual. 

4.37.1  Calling  Format 

CALL  "INQPRO"  USING  FORM-NAME, 

FIELD-NAME, 

PROMPT-NUM, 

BUF-SIZE, 

LENGTH, 

TFYT 

VREL-FIELD, 

VEXTREF, 

VINTREF, 

ROW, 

HREL-FI ELD , 

HEXTREF, 

HINTREF, 

COLUMN, 

RCODE . 


4-7  3 


UM  6203442UO 

30  September  1990 


INQPRO 


4.37.2  Parameter  Descriptions 


NAME 


I/O  FORMAT  DEFINITION 


FORM-NAME 

Input 

Str ( 10) 

The  name  of  the  containing  form 
or  the  name  of  the  form  whose 
prompt  information  you  want. 

FIELD-NAME 

Input 

Str (10) 

The  name  of  the  field  whose 
prompt  information  you  want  or 
blank  if  you  want  the  prompt 
information  for  FORM-NAME. 

PROMPT-NUM 

Input 

Num 

A  number  based  on  the  order  the 
prompts  were  defined  on  the 
form  or  field  to  indicate  which 
prompt  you  want  the  information 
about  (i.e.  a  positive  number 
of  1  or  greater  refers  to  the 
actual  order  prompts  were  de¬ 
fined;  0  refers  to  the  most  re¬ 
cently  defined  prompt;  a  nega¬ 
tive  1  or  greater  refers  to  the 
reverse  order  prompts  were  de¬ 
fined  starting  with  the  next 
most  recently  added. 

BUF-SIZE 

Input 

Num 

The  size  of  the  buffer  being 
reserved  for  the  prompt  text. 

LENGTH 

Output 

Num 

The  actual  length  of  the  prompt 
text  without  padding.  This  is 
also  the  minimum  buffer  length 
needed  to  receive  a  non-trun- 
cated  prompt  text.  Comparing 
LENGTH  with  BUF-SIZE  determines 
whether  TEXT  is  truncated  or 
padded . 

TEXT 

Output 

Str 

(BUF- 

SIZE) 

The  prompt  text,  either  padded 
with  spaces  or  truncated. 
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+ - 4 

VREL- 

FIELD 

Output 

- 4 

Str 

(120) 

The  qualified  name  of  the  field 
the  prompt  is  vertically  rela¬ 
tive  to  or  blank  if  it  is  rela¬ 
tive  to  its  containing  form. 

VEXTREF 

Output 

Num 

The  vertical  reference  point 
on  VREL-FIELD  that  the  prompt 
is  relative  to.  Values  are: 

1  -  top,  2  -  center,  and  3  - 
bottom . 

VINTREF 

Output 

Num 

The  vertical  reference  point  of 
the  prompt  that  its  position  is 
relative  to.  Values  same  as 
for  VEXTREF. 

ROW 

Output 

Num 

The  number  of  rows  the  prompt 
is  offset  from  VREL-FIELD' s 
reference  point. 

HREL- 

FIELD 

Output 

Str 

(120) 

The  qualified  name  of  the  field 
the  prompt  is  horizontally 
relative  to  or  blank  if  it  is 
relative  to  the  containing  form 

HEXTREF 

Output 

Num 

The  horizontal  reference  point 
of  the  field  the  prompt  is 
relative  to.  Values  are:  1  - 
left,  2  -  center,  and  3  -  right 

HINTREF 

Output 

Num 

The  horizontal  reference  point 
of  FIELD-NAME  or  FORM-NAME  that 
the  pprompt  is  relative  to. 
Values  the  same  as  for  HEXTREF. 

COLUMN 

Output 

Num 

The  number  of  columns  the 
prompt  is  offset  from  HREL- 
FIELD's  reference  point. 

RCODE 

4 - —  —  —  —  —  —  —  — -1 

Output 

Str (5) 

The  routine  return  code.  The 
possible  values  are  defined  in 
the  include  member  FPCODE. 
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4.37.3  Example 

WORKING-STORAGE  SECTION. 
COPY  FPCODE  OF  IISSCLIB. 
COPY  FPPARM  OF  IISSCLIB. 


01 

EXPFRM-NAME 

PIC  X(10) 

VALUE  "EXPFRM 

01 

TSTFLD-NAME 

PIC  X(10) 

VALUE  "TSTFLD 

01 

PROMPT-NUM 

PIC  S9 ( 5 ) 

COMP  VALUE  1. 

01 

BUF-SIZE 

PIC 

S9  (5) 

COMP  VALUE 

100. 

01 

PUB-LEN 

PIC 

S9  ( 5 ) 

COMP. 

01 

TEXT-BUF 

PIC 

X(100) 

01 

VREL-FIELD 

PIC  X ( 12 0 ) 

01 

VEXTREF 

PIC 

S9  (5) 

COMP. 

01 

VINTREF 

PIC 

S9(5) 

COMP. 

01 

ROW 

PIC 

S9  (5) 

COMP. 

01 

HREL-FIELD 

PIC  X ( 12 0 ) 

01 

HEXTREF 

PIC 

S9  ( 5 ) 

COMP. 

01 

HINTREF 

PIC 

S9  ( 5 ) 

COMP. 

01 

COLUMN 

PIC 

S9  (5) 

COMP. 

PROCEDURE  DIVISION, 

CALL  "INQPRO"  USING  EXPFRM-NAME , 
TSTFLD-NAME, 
PROMPT-NUM, 

BUF-SIZE, 

BUF-LEN, 

TEXT-BUF , 

VREL-FIELD, 

VEXTREF, 

VINTREF, 

ROW, 

HREL-FI ELD , 

HEXTREF, 

HINTREF, 

COLUMN, 

RCODE . 

IF  RCODE  IS  EQUAL  TO  OK 


ELSE 

CALL  " PMSGLC"  USING  RCODE. 
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4 . 38  INQSIZ 

This  routine  returns  the  size  of  a  form  or  field.  If  the 
field  is  an  array,  the  information  is  returned  for  an  element  ol 
the  array. 

4.38.1  Calling  Format 

CALL  "INQSIZ"  USING  FORM-NAME, 

FIELD-NAME, 

WIDTH, 

HEIGHT, 

RCODE . 

4.38.2  Parameter  Descriptions 


NAME  I/O  FORMAT  DEFINITION 

FORM-NAME 

Input 

Str ( 10) 

The  name  of  the  form  whose  size 
you  want  or  that  contains  the 
field  whose  size  you  want. 

FIELD-NAME 

Input 

Str(10) 

The  name  of  the  field  whose 
size  you  want  or  blank  if  you 
want  the  size  of  FORM-NAME. 

WIDTH 

Output 

Num 

The  number  of  columns  wide  the 
size  is. 

HEIGHT 

Output 

Num 

The  number  of  rows  deep  the 
size  is. 

RCODE 

Output 

Num 

The  routine  return  code.  The 
possible  values  are  defined  in 
the  include  member  FPCODE. 

+ - + - + - + - + 
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WORKING-STORAGE  SECTION. 
COPY  FPCODE  OF  IISSCLIB. 
COPY  FPPARM  OF  IISSCLIB. 


01 

EXPFRM-NAME 

PIC  X(10) 

VALUE 

"EXPFRM" . 

01 

TSTFLD-NAME 

PIC  X(10) 

VALUE 

"TSTFLD" . 

01 

WIDTH  PIC 

S9  ( 5 ) 

COMP. 

01 

HEIGHT  PIC 

S9  ( 5 ) 

COMP. 

PROCEDURE  DIVISION. 


CALL  "INQSIZ"  USING  EXPFRM-NAME, 
TSTFLD-NAME, 

WIDTH, 

HEIGHT, 

RCODE . 

IF  RCODE  IS  EQUAL  TO  OK 


ELSE 

CALL  " PMSGLC"  USING  RCODE. 
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4 . 39  INQTYP 

This  routine  returns  a  field's  type  (i.e.,  either  item, 
or  window) . 

4.39.1  Calling  Format 

CALL  "INQTYP"  USING  FORM-NAME, 

FIELD-NAME, 

FIELD-TYPE, 

RCODE . 


4.39.2  Parameter  Descriptions 


NAME 

I/O 

FORMAT 

DEFINITION 

FORM-NAME  | 

Input 

Str ( 10) 

The  name  of  the  containing  form 

FIELD-NAME 

Input 

Str (10) 

The  name  of  the  field  whose 
type  you  want  or  blank  if  you 
just  want  to  find  out  if  FORM- 
NAME  exists. 

FIELD-TYPE 

Output 

Str ( 1) 

A  character  code  to  identify 
the  type  of  field  FIELD-NAME  is 
(W  -  window,  F  -  form,  and  I  - 
item) .  If  blank,  type  will  be 

F  if  FORM-NAME  exists. 

+ - + - + - + - + 


RCODE 

+ - 


Output 


Num 


■+. 


The  routine  return  code.  The 
possible  values  are  defined  in 
the  include  member  FPCODE . 

+ - + 


form, 
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WORKING-STORAGE  SECTION. 
COPY  FPCODE  OF  IISSCLIB. 
COPY  FPPARM  OF  IISSCLIB. 


01 

EXPFRM-NAME 

PIC 

X(10) 

VALUE  "EXPFRM" . 

01 

TSTFLD-NAME 

PIC 

X(10) 

VALUE  "TSTFLD" . 

01 

TSTFLD-TYPE 

PIC 

X. 

PROCEDURE  DIVISION. 


CALL  "INQTYP"  USING  EXPFRM-NAME, 
TSTFLD-NAME , 
TSTFLD-TYPE , 

RCODE . 

IF  RCODE  IS  EQUAL  TO  OK 


ELSE 

CALL  "PMSGLC"  USING  RCODE. 
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4 .40  INQVAL 

This  routine  returns  the  value  expression  defined  for  an  iter 
field.  The  EXPRESSION  parameter  corresponds  to  the  Expression 
component  of  the  VALUE  clause  syntax  described  in  the  Form  Editor 
User's  Manual. 

4.40.1  Calling  Format 

CALL  "INQVAL"  USING  FORM-NAME, 

FIELD-NAME, 

BUF-SIZE, 

EXPRESSION, 

LENG 
RCODE . 

4.40.2  Parameter  Descriptions 

NAME  I/O  FORMAT  DEFINITION 

+ - + - + - + - + 

| FORM-NAME  | Input  |Str(10)|The  name  of  the  containing  form| 


FIELD-NAME 

b - H 

Input 

b - H 

Str ( 10) 

The  name  of  the  field  whose 
value  expression  you  want. 

BUF-SIZE 

Input 

Num 

i 

The  length  of  the  buffer  being 
reserved  for  the  value  expres¬ 
sion  . 

EXPRESSION 

Output 

Str 

(BUF- 

SIZE) 

The  value  expression  defined 
for  the  field  either  padded 
with  spaces  or  truncated. 

RCODE 

Output 

b - 

Num 

i- - J 

The  routine  return  code.  The 
possible  values  are  defined  in 
the  include  member  FPCODE. 

b - + 
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This  routine  may  first  be  called  with  a  BUF-SIZE  of  zero. 
This  forces  an  error  but  LENGTH  will  be  the  actual  buffer  size 
needed  to  store  the  value  expression. 

4.40.3  Example 

WORKING-STORAGE  SECTION. 

COPY  FPCODE  OF  IISSCLIB. 

COPY  FPPARM  OF  IISSCLIB. 

01  EXPFRM-NAME  PIC  X{10)  VALUE  "EXPFRM". 

01  TSTFLD-NAME  PIC  X(10)  VALUE  "TSTFLD" . 

01  BUF-SIZE  PIC  S9(5)  COMP  VALUE  100. 

01  VALUE-BUF  PIC  X(100). 

01  BUF-LEN  FTC  S9(5)  COMP. 

PROCEDURE  DIVISION. 


CALL  " INQVAL"  USING  EXPFRM-NAME , 
TSTFLD-NAME, 

BUF-SIZE, 

VALUE-BUF, 

BUF-LEN, 

RCODE . 

IF  RCODE  IS  EQUAL  TO  OK 


ELSE 

CALL  " PMSGLC"  USING  RCODE. 
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4.41  MAKFRM 


This  routine  creates  a  complete  form  at  run-time.  Complete 
here  means  that  no  defaults  are  used.  You  must  specify  the  size 
and  background  of  the  form.  The  form  is  open. 


4.41.1  Calling  Format 


CALL  "MAKFRM"  USING  FORM-NAME, 

BACKGROUND, 

WIDTH, 

HEIGHT, 

RCODE . 


4.41.2  Parameter  Descriptions 


NAME  I/O  FORMAT  DEFINITION 


- H 

FORM-NAME 

- - H 

Input 

h - i 

Str (10) 

The  name  of  the  form  to  be 
created . 

BACKGROUND 

Input 

:  Str ( 10) 

The  name  of  the  attribute  that 
specifies  i  ie  form's  background 

WIDTH 

Input 

1 

Num 

1 

The  number  of  columns  the  form 
will  occupy  on  its  containing 
form. 

HEIGHT 

Input 

Num 

The  number  of  rows  the  form 
will  occupy  on  its  containing 
form . 

RCODE 

- 1 

Output 

h - 1 

Num 

h - 1 

The  routine  return  code.  The 
possible  values  are  defined  in 
the  include  member  FPCODE. 

'i  o 


CALL  "MAKFRM"  USING  NEWFRM-NAME, 
XPARENT , 

ZERO-COMP, 

ZERO-COMP, 

RCODE . 

IF  RCODE  IS  EQUAL  TO  OK 


ELSE 

CALL  " PMSGLC"  USING  RCODE. 
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4.42  MOVLDV 


This  routine  is  used  to  move  the  specified  logical  device  to 
a  different  physical  device.  For  example,  you  may  want  to  route 
your  output  from  a  screen  to  a  specific  line  printer.  You  would 
specify  the  name  of  that  printer  as  well  as  its  type  (port) .  The 
valid  names  for  the  logical  and  physical  devices  are  set  up  by  the 
system  manager. 

4.42.1  Calling  Format 

CALL  "MOVLDV"  USING  LDWNID, 

DEVICE, 

DEVTYP , 

RCODE. 

4.42.2  Parameter  Descriptions 


NAME  I/O  FORMAT  DEFINITION 

LDWNID 

Input 

Num 

The  id  of  the  logical  device 
that  you  want  to  move. 

DEVICE 

Input 

Str(10) 

The  new  device  name  which  is  a 
valid  name  according  to  the 
system  manager. 

DEVTYP 

Input 

Str(10) 

The  new  device  type  which  is  a 
valid  name  according  to  the 
system  manager. 

RCODE 

1  Output 

1  Num 

1  The  routine  return  code.  The 

possible  values  are  defined  in 
the  include  member  FPCODE. 


+ - + - + - + - + 
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WORKING-STORAGE  SECTION. 
COPY  FPCODE  OF  IISSCLIB. 
COPY  FPPARM  OF  IISSCLIB. 


01 

LDWNID 

PIC 

S9  (  5 )  COMP 

01 

DEVICE 

PIC 

X (10)  . 

01 

DEVTYP 

PIC 

X(10) . 

PROCEDURE  DIVISION. 


CALL  "MOVLDV"  USING  LDWNID , 
DEVICE, 

DEVTYP , 

RCODE . 

IF  RCODE  IS  EQUAL  TO  OK 


ELSE 

CALL  "PMSGLC"  USING  RCODE. 
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4.43  MVRFLD 

This  routine  duplicates  a  field  on  all  instances  of  another 
open  form  or  on  its  containing  form  and  positions  it  either 
absolutely  or  relatively  as  specified. 

4.43.1  Calling  Format 

CALL  "MVRFLD"  USING  FORM-NAME, 

FIELD-NAME, 

COPY-FORM, 

COPY-FIELD, 

VREL-FIELD , 

VEXTREF, 

VINTREF, 

ROW, 

HREL-FIELD, 

HEXTREF, 

HINTREF, 

COLUMN, 

RCODE . 


NAME 

I/O 

FORMAT 

DEFINITION 

FORM-NAME  | 

Input  | 

Str (10) | 

The  name  of  the  containing  form 

FIELD-NAME 

Input 

Str(10) 

The  name  of  the  field  that  you 
are  copying. 

COPY-FORM 

Input 

Str ( 10) 

The  name  of  the  form  that  you 
are  copying  the  field  to.  This 
may  be  the  same  as  FORM-NAME. 

COPY-FIELD) 

- _i 

Input 

u - H 

Str ( 10) | 

L - H 

The  name  of  the  field  copy. 
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MVRFLD 


VREL- 

h - H 

Input 

h - H 

Str 

The  qualified  name  of  the  field 

FIELD 

(120) 

that  the  copied  field  position 
is  vertically  relative  to  or 
blank  if  it  is  relative  to  its 

_ 

i- - - 

h - H 

containing  form. 

VEXTREF 

Input 

Num 

The  vertical  reference  point 
on  VREL-FIELD  that  the  position 
is  relative  to.  Values  are: 

1  -  top,  2  -  center,  and  3  - 
bottom. 

VINTREF 

Input 

Num 

The  vertical  reference  point  on 
the  copied  field  that  the  posi¬ 
tion  is  relative  to.  Values 
same  as  for  VEXTREF. 

ROW 

Input 

Num 

The  number  of  rows  the  copied 
field's  position  is  offset  from 
VEXTREF' s  reference  point. 

HREL- 

FIELD 

1 

Output 

Str 

(120) 

1 

The  qualified  name  of  the  field 
that  the  copied  field  position 
is  horizontally  relative  to  or 
blank  if  it  is  relative  to  its 
containing  form. 

HEXTREF 

Output 

Num 

The  horizontal  reference  point 
on  HREL-FIELD  that  the  position 
is  relative  to.  Values  are:  1  - 
left,  2  -  center,  and  3  -  right 

HINTREF 

Output 

Num 

The  horizontal  reference  point 
on  the  copied  field  that  the 
position  is  relative  to. 

Values  the  same  as  for  HEXTREF. 

COLUMN 

Output 

Num 

The  number  of  columns  the  field 
is  offset  from  HREL-FIELD' s 
reference  point. 

RCODE 

+ - 

Output 

h - 

Str (5) 

- H 

The  routine  return  code.  The 
possible  values  are  defined  in 
the  include  member  FPCODE. 
- + 
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WORKING-STORAGE  SECTION. 
COPY  FPCODE  OF  IISSCLIB. 
COPY  FPPARM  OF  IISSCLIB. 


01 

EXPFRM-NAME 

PIC 

X(10) 

VALUE 

"EXPFRM 

01 

TSTFLD-NAME 

PIC 

X(10) 

VALUE 

"TSTFLD 

01 

NEWFLD-NAME 

PIC 

X(10) 

VALUE 

"NEWFLD 

01 

REF-FLD  NAME 

PIC 

X  ( 7 ) 

VALUE 

"TSTFLD; 

01 

TOP-LEFT-REF 

PIC 

S9  ( 5 ) 

COMP 

VALUE  1. 

01 

CENTER-REF 

PIC 

S9  (  5 ) 

COMP 

VALUE  2. 

01 

BOT-RIGHT-REF 

PIC 

S9(5) 

COMP 

VALUE  3. 

01 

ZERO-COMP  PIC 

S9  ( 5) 

COMP  VALUE  0. 

01 

TWO-COMP  PIC 

S9  ( 5 ) 

COMP  VALUE  2  . 

PROCEDURE  DIVISION. 


CALL  "MVRFLD"  USING  EXPFRM-NAME , 
TSTFLD-NAME , 
EXPFRM-NAME, 
NEWFLD-NAME, 
REF-FLD-NAME, 
BOT-RIGHT-REF, 
TOP-LEFT-REF, 

TWO-COMP, 

REF-FLD-NAME, 

CENTER-REF, 

CENTER-REF, 

ZERO-COMP, 

RCODE . 

IF  RCODE  IS  EQUAL  TO  OK 


ELSE 

CALL  " PMSGLC"  USING  RCODE. 
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4 .44  NUMELM 

This  routine  returns  the  number  of  elements  in  an  open-ended 
array. 

4.44.1  Calling  Format 

CALL  "NUMELM"  USING  ARRAY-NAME, 

ELEMENTS , 

RCODE . 

4.44.2  Parameter  Descriptions 

NAME  I/O  FORMAT  DEFINITION 


- H 

ARRAY-NAME 

h - H 

Input 

h - H 

Str 

(1-120) 

The  qualified  name  of  the  Dis¬ 
play  List  element  that  identi¬ 
fies  the  open-ended  array. 

ELEMENTS 

Output 

Num 

The  number  of  elements  in  the 
open-ended  array. 

RCODE 

Output 

l - - 

Str (5) 

The  routine  return  code.  The 
possible  values  are  defined  in 
the  include  member  FPCODE. 

4.44.3  Example 

WORKING-STORAGE  SECTION. 
COPY  FPCODE  OF  IISSCLIB. 
COPY  FPPARM  OF  IISSCLIB. 
01  PATH-NAME  PIC  X ( 11 ) 
01  NUM-ELEM  PIC  S9 (5) 
PROCEDURE  DIVISION. 


CALL  "NUMELM"  USING 
NUM-ELEM, 
RCODE. 

IF  RCODE  IS  EQUAL  TO  OK 


VALUE  "EXPFRM . ARY ; " . 
COMP. 


PATH-NAME, 


ELSE 

CALL  " PMSGLC"  USING  RCODE. 
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4.45  OISCR 

This  routine  displays  the  current  Display  List  on  the  user's 
terminal  screen  and  accepts  data  from  the  user  for  a  specified 
window.  The  user  may  only  enter  data  in  the  items  contained  in 
the  specified  window.  The  application  program  is  suspended  until 
the  user  presses  one  of  the  function  keys  that  the  FP  passes  back 
to  the  application  program.  You  may  define  the  function  keys  PFo 
through  PF20  as  you  need  for  your  application  and  the  user  will 
access  the  functions  by  toggling  the  <M0DE>  key  until  application 
mode  appears  in  the  mode  item.  The  function  keys  PFO  through  PF4 
are  pre-defined  as  <ENTER> ,  <M0DE>,  <MESSAGES>,  <HELP>,  and 
<QUIT> .  The  use  of  function  keys  is  explained  in  more  detail  in 
the  I ISS  Terminal  Operator  Guide. 

4.45.1  Calling  Format 

CALL  "OISCR"  USING  QUALIFIED-WINDOW-NAME, 

FUNCTION, 

RCODE . 

4.45.2  Parameter  Descriptions 


NAME  I/O  FORMAT  DEFINITION 


QUALIFIED- 
WIN  DOW- 
NAME 

h - 

Input 

f- - 

Str 

(1-120) 

The  qualified  name  of  the  win¬ 
dow  that  identifies  which  user 
entered  data  will  be  accepted 
for  update. 

FUNCTION 

Output 

Num 

The  number  of  the  function  key 
pressed  when  data  entry  was 
complete  (e.g.  for  <PF5>,  FUNC¬ 
TION  is  5)  . 

RCODE 

- -| 

Output 

h - - 

Str (5) 

h - - 

The  routine  return  code.  The 
possible  values  are  defined  in 
the  include  member  FPCODE. 
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OISCR 


WORKING-STORAGE  SECTION. 

COPY  FPCODE  OF  IISSCLIB. 

COPY  FPPARM  OF  IISSCLIB. 

01  FUNC  PIC  S9 ( 5 )  COMP. 

PROCEDURE  DIVISION. 


CALL  "OISCR"  USING  SCREN, 
FUNC, 

RCODE . 

IF  RCODE  IS  EQUAL  TO  OK 


ELSE 

CALL  "PMSGLC"  USING  RCODE. 
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4.46  OPNFRM 


This  routine  is  used  to  retrieve  a  form  definition.  The  form 
is  made  active  and  the  default  data  is  made  available.  If  the 
form  contains  subforms  they  are  also  opened.  All  open  forms  are 
placed  on  an  Open  List  associated  with  the  current  logical  device. 
A  form  must  then  be  put  on  the  current  Display  List  using  ADDFRM 
before  it  can  be  displayed  to  the  user.  System  performance  can 
vary  due  to  the  overhead  associated  with  form  retrieval.  When  a 
form  is  opened,  the  form  definition  is  brought  into  memory.  This 
memory  can  be  made  available  again  by  calling  CLSFRM .  Therefore, 
available  memory  and  performance  should  both  be  considered  when 
deciding  whether  to  open  and  close  forms  as  needed  or  open  all 
forms  at  the  beginning  of  the  application.  NOTE  also  that  any 
form  created  at  run-time  is  automatically  open  and  run-time 
modifications  are  made  to  forms  on  the  Open  List  associated  with 
the  current  logical  device  and  all  instances  of  a  form  on  the 
current  Display  List. 

4.46.1  Calling  Format 


CALL  "OPNFRM"  USING  FORM-NAME, 

RCODE . 

4.46.2  Parameter  Descriptions 


NAME  I/O  FORMAT  DEFINITION 


- -1 

FORM-NAME 

b - H 

Input 

b - H 

Str (10) 

The  name  of  the  form  you  want 
to  open. 

RCODE 

- H 

Output 

b - H 

Str (5) 

h - 

The  routine  return  code.  The 
possible  values  are  defined  in 
the  include  member  FPCODE. 

+ 


OPNFRM 


UM  620344200 
30  September  1990 


4.46.3  Example 


WORKING-STORAGE  SECTION. 

COPY  FPCODE  OF  IISSCLIB. 

COPY  FPPARM  OF  IISSCLIB. 

01  EXPFRM-NAME  PIC  X(10)  VALUE  "EXPFRM" . 

PROCEDURE  DIVISION. 


CALL  "OPNFRM"  USING  EXPFRM-NAME, 
RCODE . 

IF  RCODE  IS  EQUAL  TO  OK 


ELSE 

CALL  "PMSGLC"  USING  RCODE. 
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4.47  OPNLDV 


This  routine  is  used  to  open  a  new  logical  device  within  the 
application.  This  involves: 

o  creating  a  new  Open  List 
o  creating  a  new  Display  List 

o  assigning  the  Display  List  a  logical-device-id 
o  returning  the  id  to  the  application  program 

Creating  a  logical  device  does  not  destroy  any  previously 
created  logical  devices.  An  example  of  where  you  would  want  to 
open  an  additional  logical  device  is  the  case  of  an  interactive 
report  writer  where  you  need  a  logical  device  for  input  from  the 
keyboard  as  well  as  one  for  output  to  a  printer.  The  routine 
CHGLDV  is  used  to  control  which  logical  device  is  the  current 
Display  List. 

4.47.1  Calling  Format 

CALL  "OPNLDV"  USING  LOGICAL-DEVICE-ID, 

RCODE . 

4.47.2  Parameter  Descriptions 

NAME  I/O  FORMAT  DEFINITION 


LOGICAL- 

DEVICE-ID 

h - H 

Output 

h - H 

Num 

The  id  of  the  logical  device 
that  you  open. 

RCODE 

- H 

Output 

1- - H 

Str (5) 

i- - 

The  routine  return  code.  The 
possible  values  are  defined  in 
the  include  member  FPCODE. 

+ 
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4.47.3  Example 

WORKING-STORAGE  SECTION. 

COPY  FPCODE  OF  IISSCLIB. 

COPY  FPPARM  OF  IISSCLIB. 

01  LOGICAL-DEVICE-ID  PIC  S9(5)  COMP. 
PROCEDURE  DIVISION. 


CALL  "OPNLDV"  USING  LOGICAL-DEVICE-ID, 
RCODE . 

IF  RCODE  IS  EQUAL  TO  OK 


ELSE 

CALL  "PMSGLC"  USING  RCODE. 
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4.48  OUTSCR 

This  routine  displays  the  current  Display  List  on  the  user's 
terminal  screen.  Control  is  returned  immediately  to  the 
application  program  without  allowing  the  user  to  enter  any  data. 
This  routine  can  be  used  to  let  the  user  know  that  the  application 
is  "working"  when  a  long  operation  is  being  performed. 

4.48.1  Calling  Format 

CALL  "OUTSCR"  USING  QUALIFIED-WINDOW-NAME, 

RCODE . 

4.48.2  Parameter  Descriptions 


NAME 

I/O 

FORMAT 

DEFINITION 

QUALIFIED- 

WINDOW- 

NAME 

Input 

Str 

( 1-120) 

Required,  but  not  currently 
used . 

RCODE 

Output 

1- - H 

Str ( 5 ) 

i- - 

The  routine  return  code.  The 
possible  values  are  defined  in 
the  include  member  FPCODE. 

4.48.3  Example 

WORKING-STORAGE  SECTION. 
COPY  FPCODE  OF  IISSCLIB. 
COPY  FPPARM  OF  IISSCLIB. 
PROCEDURE  DIVISION. 


CALL  "OUTSCR"  USING  SCREN , 
RCODE. 

IF  RCODE  IS  EQUAL  TO  OK 


ELSE 

CALL  " PMSGLC"  USING  RCODE. 
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4 .49  PARFQN 

This  routine  lets  you  find  out  the  name  of  the  field  and  its 
type  at  a  specified  level  of  a  specified  fully  qualified  name. 
Calling  this  routine  might  be  a  natural  action  after  calling 
GETCUR.  You  would  be  able  to  find  out  exactly  where  the  action  is 
happening . 

4.49.1  Calling  Format 

CALL  "PARFQN"  USING  QUALIFIED-NAME, 

FIELD-TYPE, 

LEVEL, 

LEVEL-NAME, 

LEVEL-TYPE, 

RCODE . 

4.49.2  Parameter  Descriptions 

NAME  I/O  FORMAT  DEFINITION 

+ - + - + - + - + 


QUALIFIED- 

NAME 

Input 

Str 

(1-120) 

The  fully  qualified  name  of  the 
element  in  the  Display  List 
that  you  want  to  parse. 

FIELD-TYPE 

Input 

str (l) 

A  character  code  to  identify 
the  type  of  the  last  field  in 
the  fully  qualified  name.  Val¬ 
ues  are:  F  -  form,  W  -  window, 
and  I  -  item. 

LEVEL 

Input 

Num 

The  level  in  the  name  that  you 
want  to  identify.  1  -  top  level 
0  -  bottom  level.  Go  down  from 
the  top  with  positive  #s  or  up 
from  the  bottom  with  positive  # 

LEVEL-NAME 

Output 

Str 

(120) 

The  name  of  the  field  at  the 
specified  level  of  the  fully 
qualified  name. 

+ - + - + - + - + 
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PARFQN 


+ - + - + - + - + 

LEVEL-TYPE  Output  Str(l)  A  character  code  to  identify 

the  type  of  the  parsed  field. 
Values  are:  W  -  window,  F  - 
form  and  I  -  item. 

4 —  —  —  —  —  —  —  —  —  — -f-  —  —  — —  — — - ■  —  +  - - - + 

RCODE  Output  Str(5)  The  routine  return  code.  The 

possible  values  are  defined  in 
the  include  member  FPCODE. 

+ - + - + - + - + 


4.49.3  Examt 


WORKING-STORAGE  SECTION. 
COPY  FPCODE  OF  IISSCLIB. 
COPY  FPPARM  OF  IISSCLIB. 


01 

01 

01 

01 

QUALIFIED-NAME 
LEVEL-NAME 
TYPE1  PIC 

LEVEL-TYPE 

X. 

PIC  X ( 12 0 )  . 
PIC  X ( 12 0 )  . 

PIC  X. 

01 

ROW 

PIC 

S9  (  5 ) 

COMP. 

01 

COL 

PIC 

S9(5) 

COMP. 

01 

LEVEL 

PIC 

S9(5) 

COMP. 

PROCEDURE  DIVISION. 


CALL  "GETCUR"  USING  FULL-NAME, 
TYPE1 , 

ROW, 

COL, 

RCODE. 

CALL  "PARFQN"  USING  FULL-NAME, 
TYPE, 

LEVEL, 

LEVEL-NAME, 

LEVEL-TYPE, 

RCODE. 

IF  RCODE  IS  EQUAL  TO  OK 


ELSE 

CALL  " PMSGLC"  USING  RCODE. 
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4 . 50  PDATA 

This  routine  puts  data  in  a  Display  List  element  defined  by  a 
qualified  name.  The  specified  element  cannot  be  a  window.  This 
means  that  the  data  can  only  be  put  into  a  form  or  an  item. 
Sufficient  input  data  must  be  supplied  to  fill  the  Display  List 
elem  ,t.  The  program  MAKINC  can  be  used  to  generate  a  variable 
declaration  which  corresponds  to  the  form  definition. 

4.50.1  Calling  Format 

CALL  "PDATA"  USING  QUALIFIED-NAME, 

INPUT-DATA, 

RCODE . 


4.50.2  Parameter  Descriptions 


NAME 

I/O 

FORMAT 

DEFINITION 

QUALIFIED- 

NAME 

Input 

Str 

(1-120) 

The  fully  qualified  name  of  the 
Display  List  element  that  is  to 
receive  the  data.  The  routines 
GWINDO  and  GPAGE  may  have  to  be 
used  to  help  you  find  this  name 

IN PUT -DATA 

Input 

Var. 

The  data  structure  containing 
the  data  that  you  want  to  put 
into  the  element  specified  by 
qualified  name.  You  have  the 
option  of  defining  the  struc¬ 
ture  in  your  application  or 
using  the  structure  defined 
with  the  forms  definition  to 
MAKINC  described  in  the  Form 
Editor  User  Manual. 

RCODE 

Output 

Str (5) 

The  routine  return  code.  The 
possible  values  are  defined  in 
the  include  member  FPCODE. 

+ - + - + - + - + 
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PDATA 


.  3  Example 

WORKING-STORAGE  SECTION. 

COPY  FPCODE  OF  IISSCLIB. 

COPY  FPPARM  OF  IISSCLIB. 

01  PATH-NAME  PIC  X(7)  value  "EXPFRM; " . 
COPY  EXPFRM  OF  IISSCLIB. 

♦EXPLANATION  OF  COPY  MEMBER  EXPFRM 
*01  EXPFRM. 

*  02  FIELD1  PIC  X ( 6 )  . 

*  02  FIELD2  PIC  X(10)  . 

*  02  FIELD3  PIC  XX. 

PROCEDURE  DIVISION. 


CALL  "PDATA"  USING  PATH-NAME, 
EXPFRM, 

RCODE . 

IF  RCODE  IS  EQUAL  TO  OK 


ELSE 

CALL  " PMSGLC"  USING  RCODE. 
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4.51  PMSGLC 


This  routine  matches  a  predetermined  message  with  MCODE .  It 
then  inserts  the  message  into  the  MESSAGE-LINE  portion  of  the 
buffer  so  that  the  message  will  be  displayed  the  next  time  the 
Display  List  is  sent  to  the  user's  terminal.  Follow  this  call 
with  a  call  to  OUTSCR  or  OISCR  for  immediate  transmission.  Return 
codes  for  the  FP  routines  and  their  associated  messages  are 
defined  in  the  include  file  FPCODE.  Section  5.0  of  this  manual 
contains  a  complete  list  of  FPCODE.  The  Message  Management 
program  was  used  to  generate  this  file  and  can  be  used  to  generate 
programmer  defined  messages  and  codes.  The  Message  Management 
program  is  documented  in  the  IISS  Terminal  Operator  Guide. 

4.51.1  Calling  Format 

CALL  "PMSGLC"  USING  MCODE. 


4.51.2  Parameter  Descriptions 


+  - 


-+- 


MCODE 


Input 


Str (5) 


The  code  name  of  the  message 
that  will  be  displayed.  This 
could  be  an  RCODE  defined  in 
FPCODE  or  any  other  code  name 
associated  with  a  user  created 
message  in  another  include  file 


4.51.3  Example 

WORKING-STORAGE  SECTION. 
COPY  FPCODE  OF  IISSCLIB. 
COPY  FPPARM  OF  IISSCLIB. 
PROCEDURE  DIVISION. 


CALL" PMSGLC"  USING  MCODE. 
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4 . 52  PMSGLS 


This  routine  inserts  MSG-STRING  into  the  MESSAGE-LINE  portion 
of  the  buffer.  The  MESSAGE-LINE  will  be  displayed  the  next  time 
the  Display  List  is  sent  to  the  user's  terminal.  Follow  this  call 
with  a  call  to  OUTSCR  or  OISCR  for  immediate  transmission. 

4.52.1  Calling  Format 

CALL  "PMSGLS"  USING  MSG-STRING. 

4.52.2  Parameter  Descriptions 

4. - + - + - + - + 


MSG-STRING 

Input 

Str (60) 

The  character  string  that  is  to 
be  displayed  at  the  user's 
terminal . 

- H 

h - H 

l_ - H 

h - 

4.52.3  Example 

WORKING-STORAGE  SECTION. 

COPY  FPCODE  OF  IISSCLIB. 

COPY  FPPARM  OF  IISSCLIB. 

01  MSG-STRING  PIC  X(60)  VALUE  SPACES. 

PROCEDURE  DIVISION. 


MOVE  "YOU  HAVE  AN  ERROR"  TO  MSG-STRING. 
CALL  "PMSGLS"  USING  MSG-STRING. 
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4 . 53  PUTATT 

The  foreground  attribute  for  items  (specified  during  form 
definition  with  the  DISPLAY  AS  clause)  can  be  changed  at  run-time 
using  this  routine.  The  values  specified  during  form  definition 
are  permanent.  A  foreground  attribute  can  be  changed  permanently 
(i.e.,  for  all  following  calls  to  OUTSCR  or  OISCR  until  PUTATT  is 
called  again)  or  temporarily  (i.e.,  it  overrides  the  current 
permanent  attribute  for  the  next  call  to  OUTSCR  or  OISCR) .  When 
changed  temporarily,  the  permanent  value  becomes  effective  again 
after  the  next  call  to  OUTSCR  or  OISCR  and  the  temporary  value 
becomes  blank.  The  routine  GETATT  allows  you  to  find  out  the 
current  values  for  either  of  the  attribute  types.  Foreground 
attribute  values  that  may  only  be  defined  temporarily  are  ERROR 
and  GUARDED.  ERROR  highlights  the  item  field  in  some  manner 
(i.e.,  blinks).  This  is  useful  for  showing  a  user  that  there  is 
an  error  in  a  field  value.  GUARDED  makes  an  item  field  not 
enterable . 

4.53.1  Calling  Format 

CALL  "PUTATT"  USING  QUALIFIED-NAME, 

ATTRIBUTE -TYPE, 

ATTRIBUTE-ID, 

RCODE . 


4.53.2  Parameter  Descriptions 


NAME 


I/O 


FORMAT  DEFINITION 


QUALIFIED- 

NAME 


Input 


Str 

(1-120) 


The  fully  qualified  name  of  the 
Display  List  element  that  iden¬ 
tifies  the  item(s)  whose  attri¬ 
butes  you  want  to  change.  If 
element  is  a  form  or  a  window, 
all  items  contained  in  it  will 
be  changed. 


ATTRIBUTE- 

TYPE 


Input 


Num 


+ 


+ 


+ 


The  attribute  type  (i.e.  perma¬ 
nent  or  temporary)  you  want  to 
chang,‘.  The  include  file  FPPARM 
contains  the  definitions  for 
the  type  values  TEMP  and  PERM. 

+ - + 
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PUTATT 


ATTRIBUTE- 

ID 

Input 

Str(10) 

The  new  attribute  value  to  be 
associated  with  the  specified 
item(s)  for  the  specified  at¬ 
tribute  type.  This  can  be  a 
pre-defined  value  defined  in 
the  include  file  FPPARM,  or  a 
user-defined  attribute. 

RCODE 

Output 

h - H 

Str (5) 

1 - H 

The  routine  return  code.  The 
possible  values  are  defined  in 
the  include  member  FPCODE. 

4.53.3  Example 

WORKING-STORAGE  SECTION. 

COPY  FPCODE  OF  IISSCLIB. 

COPY  FPPARM  OF  IISSCLIB. 

01  PATH-NAME  PIC  X(12)  VALUE  " FORM1 . ITEM2 ; " . 
PROCEDURE  DIVISION. 


• 

CALL  "PUTATT"  USING  PATH-NAME, 
TEMP, 

ERR, 

RCODE . 

IF  RCODE  IS  EQUAL  TO  OK 


ELSE 

CALL  " PMSGLC"  USING  RCODE. 
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4.54  PUTBAK 


The  background  of  forms  and  windows  (specified  during  form 
definition  with  the  BACKGROUND  clause)  can  be  changed  at  run-time 
using  this  routine.  The  new  attribute  will  remain  in  effect  for 
all  following  calls  to  OUTSCR  or  OISCR  until  PUTBAK  is  called 
again.  The  routine  GETBAK  allows  you  to  find  out  the  current 
value  of  the  background  attribute  for  a  form  or  window. 

4.54.1  Calling  Format 

CALL  "PUTBAK"  USING  QUALIFIED-NAME, 

BACKGROUND-TYPE , 

BACKGROUND-ID, 

RCODE . 


4.54.2  Parameter  Descriptions 


NAME 


I/O  FORMAT  DEFINITION 

- 1 - 1 - f 

Str  The  fully  qualified  name  of  the 

(1-120)  Display  List  element  that  iden¬ 
tifies  the  form  or  window  whose 
background  you  want  to  change. 


QUALIFIED- 

NAME 


Input 


-+ 


BACKGROUND 

TYPE 


Input 


Num 


The  background  type 
anent  or  temporary) 
change.  The  include 
contains  the  definitions 
the  type  values  TEMP  and 
TEMP  is  not  supported  at 
time . 


(i.e.  perm- 
you  want  to 
file  FPPARM 
for 
PERM, 
this 


BACKGROUND 

ID 


Input 


Str ( 10' 


The  new  background  value  to  be 
associated  with  the  specified 
form  or  window  for  the  speci- 
background  type.  This  can  be  £ 
pre-defined  value  defined  in 
the  include  file  FPPARM,  or  a 
user-defined  attribute. 


RCODE 


Output 


Str(5)  j The  routine  return  code.  The 
Ipossible  values  are  defined  in 
the  include  member  FPCODE. 
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4.54.3  Example 

WORKING-STORAGE  SECTION. 

COPY  FPCODE  OF  IISSCLIB. 

COPY  FPPARM  OF  IISSCLIB. 

01  PATH-NAME  PIC  X ( 12 )  VALUE  "FORM1 . ITEM2 ; " . 
PROCEDURE  DIVISION. 


CALL  "PUTBAK"  USING  PATH-NAME, 
TEMP, 

WHITE, 

rcode . 

IF  RCODE  IS  EQUAL  TO  OK 


ELSE 

CALL  " PMSGLC"  USING  RCODE. 
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4 . 55  PUTCUR 

This  routine  allows  you  to  specify  where  the  cursor  will 
positioned  the  next  time  the  Display  List  is  sent  to  the  user 
terminal.  The  default  cursor  position  is  at  the  first  input 
if  you  do  not  use  this  routine  before  calling  OISCR. 

4.55.1  Calling  Format 

CALL  "PUTCUR"  USING  QUALIFIED-NAME, 

RCODE . 

4.55.2  Parameter  Descriptions 

NAME  I/O  FORMAT  DEFINITION 


- H 

QUALIFIED- 

NAME 

h- - H 

Input 

h - 

Str 

(1-120) 

h - 

The  qualified  name  of  the  Dis¬ 
play  List  element  that  identi¬ 
fies  the  field  you  want  the 
cursor  positioned  in. 

RCODE 

Output 

i- - - 

Str ( 5 ) 

i - 

The  routine  return  code.  The 
possible  values  are  defined  in 
the  include  member  FPCODE. 

4.55.3  Example 

WORKING-STORAGE  SECTION. 

COPY  FPCODE  OF  IISSCLIB. 

COPY  FPPARM  OF  IISSCLIB. 

01  PATH-NAME  PIC  X ( 12 )  VALUE  " FORM1 . ITEM2 ; " . 
PROCEDURE  DIVISION. 


CALL  "PUTCUR"  USING  PATH-NAME, 
RCODE. 

IF  RCODE  IS  EQUAL  TO  OK 


ELSE 

CALL  "PMSGLC"  USING  RCODE. 


4200 
19  9  0 


be 

s 

Item 
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4.56  PUTLOC 


This  routine  allows  you  to  specify  where  the  cursor  will  be 
positioned  within  a  field  the  next  time  the  Display  List  is  sent 
to  the  user's  terminal.  The  default  cursor  position  is  at  the 
first  input  item  if  you  do  not  use  this  routine  before  calling 
OISCR . 

4.56.1  Calling  Format 

CALL  "PUTLOC"  USING  QUALIFIED-NAME, 

ROW, 

COLUMN, 

RCODE . 

4.56.2  Parameter  Descriptions 

NAME  I/O  FORMAT  DEFINITION 


- H 

QUALIFIED- 

NAME 

h - H 

Input 

h - H 

Str 

(1-120) 

The  qualified  name  of  the  Dis¬ 
play  List  element  that  identi¬ 
fies  the  field  you  want  the 
cursor  positioned  in. 

ROW 

Input 

Num 

The  row  within  the  field  speci¬ 
fied  by  the  qualified  name  that 
you  want  the  cursor  to  be  posi¬ 
tioned  in. 

COLUMN 

Input 

Num 

The  column  within  the  field 
specified  by  the  qualified  name 
that  you  want  the  cursor  to  be 
positioned  in. 

RCODE 

Output 

i- - 

Str (5) 

i- - - 

The  routine  return  code.  The 
possible  values  are  defined  in 
the  include  member  FPCODE. 
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PUTLOC 


WORKING-STORAGE  SECTION. 

COPY  FPCODE  OF  IISSCLIB. 

COPY  FPPARM  OF  IISSCLIB. 

01  PATH-NAME  PIC  X(12)  VALUE  "FORM1 
01  ROW  PIC  S9 ( 5 )  COMP  VALUE  2. 

01  COLUMN  PIC  S9 ( 5 )  COMP  VALUE  3. 

PROCEDURE  DIVISION. 


CALL  "PUTLOC"  USING  " FORM1 . ITEM2 ; " , 
ROW, 

COLUMN, 

RCODE . 

IF  RCODE  IS  EQUAL  TO  OK 


ELSE 

CALL  "PMSGLC"  USING  RCODE. 
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4 . 57  PUTVTI 


This  routine  sends  application  data  to  the  Virtual  Terminal. 
The  routine  INITVT  must  be  called  first  to  enable  VT  pass-through 
mode . 

4.57.1  Calling  Format 

CALL  "PUTVTI"  USING  BUFFER, 

LENGTH, 

RCODE . 

4.57.2  Parameter  Descriptions 

NAME  I/O  FORMAT  DEFINITION 

+ - + - + - + - + 


BUFFER 

Input 

Str 

The  data  and  commands  being 

(LENG) 

sent  to  the  Virtual  Terminal . 

+ - + - + - + - + 


LENGTH 

Input 

Num  | The  actual  size  of  BUFFER. 

RCODE 

- - 

Output 

Str (5) 

The  routine  return  code.  The 
possible  values  are  defined  in 
the  include  member  FPCODE. 
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PUTVTI 


4.57.3  Example 

WORKING-STORAGE  SECTION. 

COPY  FPCODE  OF  IISSCLIB. 

COPY  FPPARM  OF  IISSCLIB. 

01  VTI-BUF  PIC  X  OCCURS  1  TO  1000  TIMES 

DEPENDING  ON  BUF-LEN. 
01  BUF-LEN  PIC  S9 ( 5 )  COMP. 

PROCEDURE  DIVISION. 


CALL  " INITVT"  USING  RCODE . 
IF  RCODE  IS  EQUAL  TO  OK 


ELSE 

CALL  "PUTVTI"  USING  VTI-BUF, 
BUF-LEN, 

RCODE 

IF  RCCDE  IS  EQUAL  TO  OK 


ELSE 

CALL  "PMSGLC"  USING  RCODE. 
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4.58  REPFLD 


This  routine  duplicates  a  field  on  all  instances  of  another 
open  form  or  on  its  containing  form.  The  copied  field  has  all  the 
characteristics  of  the  original  field  except  its  location.  The 
field  copy  does  not  have  a  location  and  will  not  appear  when  it 
containing  form  is  displayed  unless  the  routine  SETLOC  is  used 
define  a  valid  location  for  it. 

4.58.1  Calling  Format 

CALL  "REPFLD"  USING  FORM-NAME, 

FIELD-NAME, 

COPY-FORM, 

COPY-FIELD, 

RCODE . 

4.58.2  Parameter  Descriptions 

NAME  I/O  FORMAT  DEFINITION 

+ - + - + - + - + 


FORM -NAME 

Input 

|Str(10)|The  name  of  the  containing  form| 

FIELD-NAME 

Input 

Str(10) 

The  name  of  the  field  that  you 
are  copying. 

COPY-FORM 

Input 

Str (10) 

The  name  of  the  form  that  you 
are  copying  the  field  to.  This 
may  be  the  same  as  FORM-NAME. 

COPY-FIELD | 

Input  |Str(10) | The  name  of  the  field  copy.  | 

RCODE 

Output 

Str (5) 

The  routine  return  code.  The 
possible  values  are  defined  in 
the  include  member  FPCODE. 

+ - + - + - + - + 
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REPFLD 


WORKING-STORAGE  SECTION. 
COPY  FPCODE  OF  IISSCLIB. 
COPY  FPPARM  OF  IISSCLIB. 


01 

EXPFRM-NAME 

PIC 

X(10) 

VALUE 

"EXPFRM" . 

01 

TSTFLD-NAME 

PIC 

X(10) 

VALUE 

"TSTFLD" . 

01 

NEWFLD-NAME 

PIC 

X(10) 

VALUE 

"NEWFLD" . 

PROCEDURE  DIVISION. 


CALL  "REPFLD"  USING  EXPFRM-NAME, 
TSTFLD-NAME, 
EXPFRM-NAME, 
NEWFLD-NAME , 

RCODE . 

IF  RCODE  IS  EQUAL  TO  OK 


ELSE 

CALL  "PMSGLC"  USING  RCODE. 
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4.59  REPFRM 


This  routine  duplicates  an  open  form  with  a  new  name.  The 
copied  form  has  all  the  characteristics  of  the  original  form. 
NOTE  that  all  instances  of  the  form  in  the  Display  List  are  not 
copied. 

4.59.1  Calling  Format 

CALL  "REPFRM"  USING  FORM-NAME, 

COPY -NAME, 

RCODE . 

4.59.2  Parameter  Descriptions 

NAME  I/O  FORMAT  DEFINITION 

+ - + - + - + - + 


FORM-NAME 

Input 

Str (10) 

The  name  of  the  form  you  are 
making  a  copy  of. 

|  COPY-NAME  J 

Input  ! 

Str (10) | The  name  of  the  form  copy. 

RCODE 

Output 

Str (5) 

The  routine  return  code.  The 
possible  values  are  defined  in 
the  include  member  FPCODE. 

+ - + - + - + - + 
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REPFRM 


WORKING-STORAGE  SECTION. 

COPY  FPCODE  OF  IISSCLIB. 

COPY  FPPARM  OF  IISSCLIB. 

01  EXPFRM-NAME  PIC  X(10)  VALUE  "EXPFRM" . 

01  NEWFRM-NAME  PIC  X(10)  VALUE  "NEWFRM" . 

PROCEDURE  DIVISION. 


CALL  "REPFRM"  USING  EXPFRM-NAME , 
NEWFRM-NAME, 

RCODE . 

IF  RCODE  IS  EQUAL  TO  OK 


ELSE 

CALL  " PMSGLC"  USING  RCODE. 
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4.60  RMVAPR 


This  routine  removes  the  criterion  defined  for  specifying 
when  a  field  appears  on  its  containing  form.  This  criterion 
corresponds  to  the  Criterion  component  of  the  APDEARS  IF  clause 
syntax  described  in  the  Form  Editor  User's  Manual. 

4.60.1  Calling  Format 

CALL  "RMVAPR"  USING  FORM-NAME, 

FIELD-NAME, 

RCODE . 


4.60.2  Parameter  Descriptions 


NAME 

I/O 

FORMAT 

DEFINITION 

|  FORM-NAME  | Input  | 

Str(10) | 

The  name  of  the  containing  form 

FIELD-NAME 

Input 

Str ( 10) 

The  name  of  the  field  whose 
appears  if  criterion  you  want 
to  remove. 

RCODE 

Output 

Str (5) 

The  routine  return  code.  The 
possible  values  are  defined  in 
the  include  member  FPCODE. 

+ - + - + - + - + 


4.60.3  Example 

WORKING-STORAGE  SECTION. 

COPY  FPCODE  OF  IISSCLIB. 

COPY  FPPARM  OF  IISSCLIB. 

01  EXPFRM-NAME  PIC  X(10)  VALUE  " EXPFRM" . 

01  TSTFLD-NAME  PIC  X(10)  VALUE  "TSTFLD" . 

PROCEDURE  DIVISION. 


CALL  "RMVAPR"  USING  EXPFRM-NAME, 
TSTFLD-NAME, 

RCODE . 
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4.61  RMVARY 


This  routine  removes  all  array  dimensions  from  a  field, 
means  there  is  only  one  occurrence  of  the  field  on  its  conta 
form. 

4.61.1  Calling  Format 

CALL  "RMVARY"  USING  FORM-NAME, 

FIELD-NAME, 

RCODE . 

4.61.2  Parameter  Descriptions 

NAME  I/O  FORMAT  DEFINITION 

l - 1 - 1 - 1 - t- 


|  FORM-NAME 

Input 

Str(10)  j 

The  name  of  the  containing  form 

FIELD-NAME 

Input 

Str ( 10) 

The  name  of  the  field  you  no 
longer  want  to  be  an  array. 

RCODE 

Output 

h - H 

Str (5) 

h - H 

The  routine  return  code.  The 
possible  values  are  defined  in 
the  include  member  FPCODE. 

This 

ning 
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3  Example 

WORKING-STORAGE  SECTION. 

COPY  FPCODE  OF  IISSCLIB. 

COPY  FPPARM  OF  IISSCLIB. 

01  EXPFRM-NAME  PIC  X(10)  VALUE  "EXPFRM"  . 

01  ARYFLD-NAME  PIC  X(10)  VALUE  "ARY". 

PROCEDURE  DIVISION. 


CALL  "RMVARY"  USING  EXPFRM-NAME, 
ARYFLD-NAME, 

RCODE . 

IF  RCODE  IS  EQUAL  TO  OK 


ELSE 

CALL  "PMSGLC"  USING  RCODE. 
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4.62  RMVATT 


This  routine  deletes  one  or  all  of  the  attributes  defined  for 
a  form.  Form  attributes  are  defined  with  the  ATTRIBUTE  clause 
described  in  the  Form  Editor  User's  Manual. 

4.62.1  Calling  Format 

CALL  "RMVATT"  USING  FORM-NAME, 

ATTRIBUTE-ID, 

RCODE . 

4.62.2  Parameter  Descriptions 

NAME  I/O  FORMAT  DEFINITION 


FORM-NAME 

Input 

Str(10) 

The  name  of  the  form  whose  at¬ 
tribute  (s)  you  want  to  delete. 

ATTRIBUTE- 

ID 

Input 

Str (10) 

The  name  of  the  specific  at¬ 
tribute  you  waant  to  delete  or 
blank  to  delete  all  the  form's 
attributes . 

RCODE 

Output 

Str (5) 

The  routine  return  code.  The 
possible  values  are  defined  in 
the  include  member  FPCODE. 
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4.62.3  Example 

WORKING-STORAGE  SECTION. 

COPY  FPCODE  OF  IISSCLIB. 

COPY  FPPARM  OF  IISSCLIB. 

01  EXPFRM-NAME  PIC  X(10)  VALUE  "EXPFRM" . 

01  TSTATR-NAME  PIC  X(10)  VALUE  "TESTATTR" . 

PROCEDURE  DIVISION. 


CALL  "RMVATT"  USING  EXPFRM-NAME, 
TSTATR-NAME, 

RCODE . 

IF  RCODE  IS  EQUAL  TO  OK 


ELSE 

CALL  " PMSGLC"  USING  RCODE. 
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4.63  RMVDIM 


This  routine  removes  a  field's  array  dimension. 

4.63.1  Calling  Format 

CALL  "RMVDIM"  USING  FORM-NAME, 

FIELD-NAME, 

DIM-INDEX, 

RCODE . 

4.63.2  Parameter  Descriptions 

NAME  I/O  FORMAT  DEFINITION 


h - H 

FORM-NAME 

h - H 

Input 

h - H 

Str(10) 

The  name  of  the  containing  form| 

FIELD-NAME 

Input 

Str ( 10) 

The  name  of  the  field  whose 
array  dimension  you  want  to 
remove . 

DIM-INDEX 

Input 

Num 

A  number  to  indicate  which  dim¬ 
ension  to  remove  where  1  refers 
to  the  most  inclusive,  2  the 
next  most  inclusive,  and  so  on. 

RCODE 

Output 

— 

Str (5) 

— 

The  routine  return  code.  The 
possible  values  are  defined  in 
the  include  member  FPCODE. 
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RMVDIM 


WORKING-STORAGE  SECTION. 

COPY  FPCODE  OF  IISSCLIB. 

COPY  FPPARM  OF  IISSCLIB. 

01  EXPFRM-NAME  PIC  X(10)  VALUE  "EXPFRM". 

01  ARYFLD-NAME  PIC  X(10)  VALUE  "ARY". 

01  TWO-COMP  PIC  S9  ( 5 )  COMP  VALUE  2. 

PROCEDURE  DIVISION. 


CALL  "RMVDIM"  USING  EXPFRM-NAME, 
ARYFLD-NAME, 

TWO-COMP, 

RCODE . 

IF  RCODE  IS  EQUAL  TO  OK 


ELSE 

CALL  " PMSGLC"  USING  RCODE. 
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4 . 64  RMVDOM 

This  routine  removes  the  domain  options  defined  for  an  item 
field.  Domain  options  correspond  to  DOMAIN  clause  options 
described  in  the  Form  Editor  User's  Manual. 

4.64.1  Calling  Format 

CALL  "RMVDOM"  USING  FORM-NAME, 

ITEM-NAME, 

RCODE . 

4.64.2  Parameter  Descriptions 


NAME  I/O  FORMAT  DEFINITION 

FORM-NAME  ] 

Input 

|  Str ( 10) 

The  name  of  the  containing  form 

ITEM-NAME 

Input 

Str ( 10) 

The  name  of  the  item  field 
whose  domain  options  you  want 
to  remove. 

RCODE 

Output 

Str (5) 

The  routine  return  code.  The 
possible  values  are  defined  in 
the  include  member  FPCODE. 

+ - + - H - + - + 
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4.64.3  Example 

WORKING-STORAGE  SECTION. 

COPY  FPCODE  OF  IISSCLIB. 

COPY  FPPARM  OF  IISSCLIB. 

01  EXPFRM-NAME  PIC  X ( 10)  VALUE 

01  TSTFLD-NAME  PIC  X(10)  VALUE 

PROCEDURE  DIVISION. 


CALL  "RMVDOM"  USING  EXPFRM-NAME, 
TSTFLD-NAME, 

RCODE . 

IF  RCODE  IS  EQUAL  TO  OK 


ELSE 

CALL  "PMSGLC"  USING  RCODE. 
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4 . 65  RMVFLD 

This  routine  deletes  a  specified  field  from  an  open  form  and 
all  instances  of  the  form  on  the  current  Display  List. 

4.65.1  Calling  Format 

CALL  "RMVFLD"  USING  FORM-NAME, 

FIELD-NAME, 

RCODE . 

4.65.2  Parameter  Descriptions 


NAME 

I/O 

FORMAT 

DEFINITION 

|  FORM-NAME  | 

Input 

Str (10) | 

The  name  of  the  containing  form 

FIELD-NAME 

Input 

Str (10) 

The  name  of  the  field  you  want 
to  delete. 

RCODE 

Output 

Str (5) 

The  routine  return  code.  The 
possible  values  are  defined  in 
the  include  member  FPCODE. 

.65.3  Exam? 

3le 

WORKING-STORAGE  SECTION. 
COPY  FPCODE  OF  IISSCLIB. 
COPY  FPPARM  OF  IISSCLIB. 
01  EXPFRM-NAME 
01  TSTFLD-NAME 
PROCEDURE  DIVISION. 


PIC  X(10)  VALUE  " EXPFRM" . 
PIC  X(10)  VALUE  "TSTFLD" . 


CALL  "RMVFLD"  USING  EXPFRM-NAME, 
TSTFLD-NAME, 

RCODE. 

IF  RCODE  IS  EQUAL  TO  OK 


ELSE 

CALL  " PMSGLC"  USING  RCODE. 


4-126 


RMVHLP 


UM  620344200 
30  September  1990 


4.66  RMVHLP 


This  routine  removes  the  help  information  defined  for  an  item 
field. 

4.66.1  Calling  Format 

CALL  "RMVHLP"  USING  FORM-NAME, 

ITEM-NAME, 

RCODE . 

4.66.2  Parameter  Descriptions 

NAME  I/O  FORMAT  DEFINITION 


- 4- - h 

FORM-NAME  | Input 

Str(10) | The  name  of  the  containing  form 

ITEM-NAME 

Input 

Str(10) 

The  name  of  the  field  whose 
help  information  you  want  to 
delete. 

RCODE 

Output 

Str ( 5 ) 

The  routine  return  code.  The 

possible  values  are  defined  in 
the  include  member  FPCODE. 


+ - + - 4- - + 


4.66.3  Example 

WORKING-STORAGE  SECTION. 

COPY  FPCODE  OF  IISSCLIB. 

COPY  FPPARM  OF  IISSCLIB. 

01  EXPFRM-NAME  PIC  X(10)  VALUE  " EXPFRM" . 

01  TSTFLD-NAME  PIC  X ( 1 0 )  VALUE  "TSTFLD" . 

PROCEDURE  DIVISION. 


CALL  "RMVHLP"  USING  EXPFRM-NAME, 
TSTFLD-NAME, 

RCODE. 

IF  RCODE  IS  EQUAL  TO  OK 


ELSE 

CALL  " PMSGLC"  USING  RCODE. 
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4 . 67  RMVPAG 

This  routine  changes  the  current  Display  List  by  removing 
pages  from  a  window.  If  there  are  pages  with  higher  page  numbers 
than  the  page  specified,  they  are  also  removed. 

4.67.1  Calling  Format 

CALL  "RMVPAG"  USING  QUALIFIED-WINDOW-NAME, 

PAGE-NUMBER, 

RCODE . 

4.67.2  Parameter  Descriptions 

NAME  I/O  FORMAT  DEFINITION 

+ - + - + - + - + 


QUALIFIED- 

WINDOW- 

NAME 

Input 

Str 

( 1-120) 

The  qualified  name  of  the  Dis¬ 
play  List  element  that  identi¬ 
fies  the  window  the  page(s) 
will  be  removed  from. 

PAGE- 

NUMBER 

Input 

Num 

The  number  identifying  the  lat¬ 
est  page  that  will  be  removed 
from  the  window. 

RCODE 

Output 

Str  (  5 )  1 

The  routine  return  code.  The 
possible  values  are  defined  in 
the  include  member  FPCODE. 

4 - (- - 1 - 1 - 1- 
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4.67.3  Example 


WORKING-STORAGE  SECTION. 

COPY  FPCODE  OF  IISSCLIB. 

COPY  FPPARM  OF  IISSCLIB. 

01  PAGE-NUMBER  PIC  S9(5)  COMP  VALUE  1. 

PROCEDURE  DIVISION. 


CALL  "RMVPAG"  USING  SCREN, 

PAGE-NUMBER 
RCODE . 

IF  RCODE  IS  EQUAL  TO  OK 


ELSE 

CALL  " PMSGLC"  USING  RCODE. 
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4 . 68  RMVPRO 

This  routine  removes  prompts  from  a  field  or  a  form.  If 
multiple  prompts  contain  the  same  text,  all  such  prompts  are 
removed.  You  can  also  specify  to  remove  all  prompts  from  the  form 
or  field. 

4.68.1  Calling  Format 

CALL  "RMVPRO"  USING  FORM-NAME, 

FIELD-NAME, 

LENGTH, 

PROMPT-TEXT, 

RCODE . 


NAME 

I/O 

FORMAT 

DEFINITION 

FORM-NAME 

Input 

Str (10) 

The  name  of  the  form  whose 
prompts  you  want  to  remove  or 
that  contains  the  field  whose 
prompts  you  want  to  remove. 

FIELD-NAME 

- H 

LENGTH 

Input 

b - H 

Input 

Str(10) 

1 - H 

Num 

The  name  of  the  field  whose 
prompts  you  want  to  remove  or 
blank  if  you  want  to  remove 
prompts  from  FORM-NAME. 

The  length  of  the  prompt  text 
to  be  removed  to  0  to  remove 
all  the  prompts  on  the  form  or 
field. 

PROMPT- 

TEXT 

Input 

Str 

(LENG) 

The  actual  prompt  text  to  be 
removed.  This  parameter  is  ig¬ 
nored  if  LENGTH  is  0. 

RCODE 

- 1 

Output 

b - H 

St r ( 5 ) 

b - H 

The  routine  return  code.  The 
possible  values  are  defined  in 
the  include  member  FPCODE. 

h - 
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RMVPRO 


WORKING-STORAGE  SECTION. 
COPY  FPCODE  OF  IISSCLIB. 
COPY  FPPARM  OF  IISSCLIB. 


01 

EXPFRM-NAME 

PIC 

X  ( 10) 

VALUE 

"EXPFRM" . 

01 

BLANK-NAME 

PIC 

X(10) 

VALUE 

SPACES . 

01 

PROMPT-LEN 

PIC 

S9  ( 5 ) 

COMP  ' 

VALUE  12. 

01 

PROMPT-TXT 

PIC 

X  ( 12 ) 

VALUE 

"EXAMPLE  FORM" 

PROCEDURE  DIVISION. 


CALL  "RMVPRO"  USING  EXPFRM-NAME , 
BLANK-NAME , 

PROMPT-LEN, 

PROMPT-TXT , 

RCODE . 

IF  RCODE  IS  EQUAL  TO  OK 


ELSE 

CALL  " PMSGLC"  USING  RCODE. 
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4 . 69  RMVVAL 

This  routine  removes  the  value  expression  defined  for  an  item 
field.  This  expression  corresponds  to  the  Expression  component  ot 
the  VALUE  clause  syntax  described  in  the  Form  Editor  User's 

Manual . 


4.69.1  Callinq  Format 


CALL  "RMVVAL"  USING  FORM-NAME, 

FIELD-NAME, 

RCODE . 


4.69 


Parameter  Descriptions 


NAME  I/O  FORMAT  DEFINITION 


- -1 

FORM-NAME  | 

- 4 

Input  | 

- H 

Str ( 10) | 

The  name  of  the  containing  form 

FIELD-NAME 

Input 

Str ( 10) 

The  name  of  the  field  whose 
value  expression  you  want  to 
oelete . 

RCODE 

h - H 

Output 

y - J 

Str ( 5 ) 

i- - - 

The  routine  return  code.  The 
possible  values  are  defined  in 
the  include  member  FPCODE. 

4  -  1  3  2 


RMVVAL 


4.69.3  Example 

WORKING-STORAGE  SECTION. 

COPY  FPCODE  OF  IISSCLIB. 

COPY  FPPARM  OF  IISSCLIB. 

01  EXPFRM-NAME  PIC  X(10)  VALUE 

01  TSTFLD-NAME  PIC  X(10)  VALUE 

PROCEDURE  DIVISION. 


CALL  "RMVVAL"  USING  EXPFRM-NAME , 
TSTFLD-NAME, 

RCODE . 

IF  RCODE  IS  EQUAL  TO  OK 


ELSE 

CALL  " PMSGLC"  USING  RCODE. 
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"EXPFRM" . 
"TSTFLD" . 
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4 .70  RPLFRM 

This  routine  allows  you  to  change  a  specified  page  ol  a 
window  on  the  current  Display  List  by  replacing  the  form 
currently  on  the  page  with  a  new  form.  The  pages  above  and  be  1 
the  specified  page  remain  unchanged. 

4.70.1  Calling  Format 

CALL  "RPLFRM"  USING  QUALIFIED-WINDOW-NAME, 

PAGE-NUMBER, 

FORM-NAME, 

RCODE . 

4.70.2  Parameter  Descriptions 


NAME 

I/O 

FORMAT 

DEFINITION 

QUALIFIED- 

WINDOW- 

NAME 

Input 

St  r 

(1-120) 

The  qualified  name  of  the  Dis¬ 
play  List  element  that  identi¬ 
fies  the  window  that  contains 
the  page  you  want  to  change. 

PAGE- 

NUMBER 

Input 

Num 

The  number  identifying  the  page 
you  want  to  change. 

FORM-NAME 

Input 

Str ( 10) 

The  name  of  the  new  form  that 
the  page  will  contain. 

RCODE 

Output 

Str ( 5) 

j - - 

!  The  routine  return  code.  The 
j possible  values  are  defined  in 
the  include  member  FPCODE. 
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4 . 70 


RPLFRM 


3  Example 

WORKING-STORAGE  SECTION. 

COPY  FPCODE  OF  IISSCLIB. 

COPY  FPPARM  OF  IISSCLIB. 

01  EXPFRM-NAME  PIC  X(10)  VALUE  "EXPFRM" . 

01  CURPAG  PIC  S9 ( 5 )  COMP  VALUE  2. 

PROCEDURE  DIVISION. 


CALL  "RPLFRM"  USING  SCREN, 
CURPAG, 
EXPFRM-NAME , 
RCODE . 

IF  RCODE  IS  EQUAL  TO  OK 


ELSE 

CALL  " PMSGLC"  USING  RCODE. 
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4.71  SAVFRM 


This  routine  saves  a  form  that  is  created  or  modified  at 
run-time.  You  can  save  the  FDL  source  for  the  form,  the  compiled 
form  or  both.  If  the  form  already  exists,  you  can  also  specify 
whether  it  should  be  overwritten.  NOTE  that  the  saved  FDL  source 
can  be  modified  outside  of  the  application. 


4.71.1  Calling  Format 


CALL  "SAVFRM"  USING  FORM-NAME, 

SAVE-MODE, 

OVRIT-FLAG , 

RCODE . 


71.2  Parameter  Descriptions 


NAME  I/O  FORMAT  DEFINITION 


- -1 

FORM-NAME 

- -l 

Input 

- -t 

Str (10) 

The  name  of  the  form  to  be 
saved . 

SAVE-MODE 

Input 

Str (1) 

A  character  code  to  specify  how 
to  save  the  form.  Values  are: 

C  -  compiled  form,  S  -  FDL 
source,  B  -  both. 

OVRIT-FLAG 

Input 

Num 

An  overwrite  flag.  0  -  do  not 
overwrite  the  source  file  if  it 
already  exists.  1  -  overwrite 
any  existing  source  file. 

RCODE 

Output 

f- - 

Str (5) 

i - 

The  routine  return  code.  The 
possible  values  are  defined  in 
the  include  member  FPCODE. 
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4.71.3  Example 

WORKING-STORAGE  SECTION. 

COPY  FPCODE  OF  IISSCLI8. 

COPY  FPPARM  OF  IISSCLIB. 

01  EXPFRM-NAME  PIC  X(10)  VALUE 

01  BOTH-MODE  PIC  X  VALUE  "B". 

01  OVERWRITE  PIC  S9(5)  COMP  VALUE  1. 
PROCEDURE  DIVISION. 


CALL  "SAVFRM"  USING  EXPFRM-NAME , 
BOTH-MODE , 

OVERWRITE, 

RCODE . 

IF  RCODE  IS  EQUAL  TO  OK 


ELSE 

CALL  " PMSGLC"  USING  RCODE. 


"  EXPFRM" . 
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4.72  SETAPR 


This  routine  allows  you  to  define  the  criterion  for  when  a 
field  appears  on  a  form.  This  criterion  corresponds  to  the 
Criterion  component  in  the  APPEARS  IF  clause  syntax  described  in 
the  Form  Editor  User's  Manual. 

4.72.1  Calling  Format 

CALL  "SETAPR"  USING  FORM-NAME, 

FIELD-NAME, 

LENGTH, 

CRITERION, 

RCODE . 


4.72.2  Parameter  Descriptions 


NAME  I/O  FORMAT  DEFINITION 

+ - + - + - + - + 

| FORM-NAME  | Input  |Str(10) | The  name  of  the  containing  form| 
+ - + - + - + - 


ITEM-NAME 

Input 

Str ( 10) 

The  name  of  the  field  whose 
appears  ’ f  criterion  you  want 
to  define. 

LENGTH 

Input 

Num 

The  length  of  the  string 
contains  the  criterion. 

that 

CRITERION 

Input 

Str 

(LENG) 

The  string  containing  the 
terion. 

■  cri- 

RCODE 

I  Output 

Str (5) 

The  routine  return  code. 

The 

possible  values  are  defined  in 
the  include  member  FPCODE. 


—  —  —  —  —  —  —  —  —  —  -f  —  —  —  —  —  —  -f  —  —  _  —  —  —  —  —  —  -  - - -  -  -  -  -  -  -  -  -  -  - - —  —  —  —  —  -f- 
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4.72.3  Example 

WORKING-STORAGE  SECTION. 
COPY  FPCODE  OF  IISSCLIB. 


COPY 

FPPARM  OF 

IISSCLIB. 

01 

EXPFRM-NAME 

PIC  X(10) 

VALUE 

" EXPFRM" . 

01 

TSTFLD-NAME 

PIC  X(10) 

VALUE 

"TSTFLD" . 

01 

CRIT-TXT 

PIC 

X(  12) 

VALUE  " ' TSTFLD 1 

>  0". 

01 

CRIT-LEN 

PIC 

S9  ( 5 ) 

COMP  VALUE 

:  12 . 

PROCEDURE  DIVISION. 


CALL  "SETAPR"  USING  EXPFRM-NAME, 
TSTFLD-NAME , 

CRIT-LEN, 

CRIT-TXT , 

RCODE . 

IF  RCODE  IS  EQUAL  TO  OK 


ELSE 

CALL  " PMSGLC"  USING  RCODE. 
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4.73  SETATT 


This  routine  defines  a  new  attribute  for  a  form  or  mcdil'i 
an  existing  one.  The  routine  parameters  correspond  to  the 
components  of  the  ATTRIBUTE  clause  syntax  described  in  the  For 
Editor  User's  Manual. 

4.73.1  Calling  Format 

CALL  "SETATT"  USING  FORM-NAME, 

ATTRIBUTE- ID, 

BACK-COLOR, 

DISPLAY-COLOR, 

LENGTH, 

PRIMITIVES , 

RCODE . 


4.73.2  Parameter  Descriptions 


NAME  I/O  FORMAT  DEFINITION 


- H 

FORM-NAME 

- - H 

Input 

r - 1 

Str (10) 

The  name  of  the  form  whose  at¬ 
tribute  you  want  to  define  or 
mod i f y . 

ATTRIBUTE- 

ID 

Input 

1 

Str ( 10) 1 

! 

The  name  of  the  attribute  to 
define  or  modify. 

BACK-COLOR 

Input 

Str (10) (The  background  color  primitive 
or  blank  to  not  change  it. 

DISPLAY- 

COLOR 

Input 

Str ( 10) 

The  display  color  primitive  or 
blank  to  not  change  or  set  it. 

LENGTH 

I  nput 

h - 

Nun 

L - 

The  length  of  the  string  con¬ 
taining  the  primitives,  includ¬ 
ing  separating  characters  of 
spaces  or  commas,  or  blank  if 
the  attribute  only  contains 
color  primitives. 

h - 
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SET ATT 


- H 

PRIMITIVES 

- H 

Input 

r - H 

Str 

(LENG) 

The  attribute  primitives  other 
than  color.  Valid  values  are 
listed  following  the  parameter 
descriptions . 

RCODE 

- H 

Output 

h - - 

Str (5) 

h - 

The  routine  return  code.  The 
possible  values  are  defined  in 
the  include  member  FPCODE. 

Valid  attribute  primitives  are: 

BOLD  DIM 

UNDERSCORE  SLOWBLINK 

FASTBLINK  HIDDEN 

GUARDED  REVERSE 

ORED  NOWRITE 
TABFIELD 

These  values  and  some  pre-defined  attribute-ids  are  described 
in  the  Form  Editor  User's  Manual. 
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4.73.3  Example 


WORKING-STORAGE  SECTION. 
COPY  FPCODE  OF  IISSCLIB. 
COPY  FPPARM  OF  IISSCLIB. 
01  EXPFRM-NAME 
01  TSTATR-NAME 
01  PRIMITIVES 
01  PRIM-LEN  PIC  S9 ( 5 ) 
PROCEDURE  DIVISION. 


PIC  X(10)  VALUE 
PIC  X(10)  VALUE 
PIC  X ( 12 )  VALUE 
COMP  VALUE  12. 


CALL  "SETATT"  USING  EXPFRM-NAME, 
TSTATR-NAME, 

YELLOW, 

BLACK, 

PRIM-LEN, 

PRIMITIVES, 

RCODE . 

IF  RCODE  IS  EQUAL  TO  OK 


ELSE 

CALL  "PMSGLC"  USING  RCODE. 


"  EXPFRM" . 
"TESTATTR"  . 
"BOLD, GUARDED"  . 
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4.74  SETDIM 


This  routine  allows  you  to  change  how  a  field  array  dimension 
is  defined.  The  routine  parameters  correspond  to  the  components 
of  the  Repeat  Spec  syntax  described  in  the  Form  Editor  User's 
Manual . 

4.74.1  Calling  Format 

CALL  "SETDIM"  USING  FORM-NAME, 

FIELD-NAME, 

DIM-INDEX, 

DISPLAY-SIZE, 

ACTUAL-SIZE, 

DIRECTION, 

SPACES , 

RCODE . 

4.74.2  Parameter  Descriptions 


NAME  I/O  FORMAT  DEFINITION 


FORM-NAME  | 

r - H 

Input  j 

Str(10) | The  name  of  the  containing  form 

FIELD-NAME 

Input 

l 

Str (10) 

i 

The  name  of  the  field  whose 
array  dimension  you  want  to 
change . 

DIM-INDEX 

Input 

Num 

A  number  to  indicate  which 
array  dimension  you  want  to 
change.  1  -  most  inclusive 
dimension.  2  -  the  next  most 
inclusive,  and  so  on. 

DISPLAY- 

SIZE 

|  Input 

Num 

The  number  of  array  elements  to 
be  displayed.  0  -  open-ended. 

ACTUAL- 

SIZE 

Input 

Num 

The  actual  number  of  array 
elements  there  are.  0  -  open- 
ended  . 
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DIRECTION 

Input 

Str(l) 

A  character  code  to  specify 
whether  the  array  elements  re¬ 
peat  vertically  (V)  or  horizon¬ 
tally  (H)  . 

SPACES 

Input 

Num 

The  number  of  spaces  to  leave 
between  repetitions. 

RCODE 

+ - 

Output 

-  -1 - 

Str ( 5 ) 

j - 

The  routine  return  code.  The 
possible  values  are  defined  in 
the  include  member  FPCODE. 

-+ - 

4.74.3  Example 

WORKING-STORAGE  SECTION. 

COPY  FPCODE  OF  IISSCLIB. 

COPY  FPPARM  OF  IISSCLIB. 

01  EXPFRM-NAME  PIC  X(10)  VALUE  "EXPFRM" . 

01  TSTFLD-NAME  PIC  X(10)  VALUE  "TSTFRD" . 

01  DIM-INDEX  PIC  S9 ( 5 )  COMP  VALUE  1. 

01  DSP-SIZE  PIC  S9 ( 5 )  COMP  VALUE  10. 

01  ACT-SIZE  PIC  S9 ( 5 )  COMP  VALUE  20. 

01  NUM-SPACES  PIC  S9(5)  COMP  VALUE  0. 

01  RPT- DIRECT I ON  PIC  X  VALUE  "V". 

PROCEDURE  DIVISION. 


CALL  "SETDIM"  USING  EXPFRM-NAME, 

TSTFLD-NAME, 

DIM- INDEX, 

DSP-SIZE, 

ACT -SIZE, 

NUM-SPACES , 

RPT-DI RECTION , 

RCODE . 

IF  RCODE  IS  EQUAL  TO  OK 


F  LS  F 

CAIT.  "  F’MSGLC"  USING  RCODE. 
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4.75  SETDIS 

This  routine  defines  or  changes  the  display  attribute  for  a 
field.  This  attribute  corresponds  to  the  Attribute_id  component 
in  the  DISPLAY  AS  clause  syntax  described  in  the  Form  Editor 
User's  Manual. 

4.75.1  Calling  Format 

CALL  "SETDIS"  USING  FORM-NAME, 

FIELD-NAME, 

ATTRIBUTE-ID, 

RCODE . 

4.75.2  Parameter  Descriptions 

NAME  I/O  FORMAT  DEFINITION 

+ - + - + - + - + 


|  FORM-NAME  j 

Input 

Str(10) | The  name  of  the  containing  form| 

FIELD-NAME 

Input 

Str ( 10) 

The  name  of  the  field  whose 
display  attribute  you  want  to 
change  or  define. 

ATTRIBUTE- 

ID 

Input 

Str(10) 

The  name  of  the  display  attrib- I 
ute.  This  value  must  be  pre¬ 
viously  defined  for  the  form 
using  SETATT  or  one  of  the 
valid  pre-defined  attributes 
contained  in  the  include  file 
FPPARM . 

RCODE 

Output 

h - H 

Str (5) 

i- - 

The  routine  return  code.  The 
possible  values  are  defined  in 
the  include  member  FPCODE. 

i - + 
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WORKING-STORAGE  SECTION. 

COPY  FPCODE  FROM  IISSCLIB. 

COPY  FPPARM  FROM  IISSCLIB. 

01  EXPFRM-NAME  PIC  X(10)  VALUE  " EXPFRM" . 

01  TSTFLD-NAME  PIC  X(10)  VALUE  "TSTFLD" . 

PROCEDURE  DIVISION. 


CALL  "SETDIS"  USING  EXPFRM-NAME, 

TSTFLD-NAME, 

OUTP , 

RCODE . 

IF  RCODE  IS  EQUAL  TO  OK 


ELSE 

CALL  " PMSGLC"  USING  RCODE. 


4-146 


SETDOM 


UM  02  0  J  4  -i  2  uo 
30  September  1990 


4 .76  SETDOM 

This  routine  defines  the  domain  options  for  an  item  field. 
These  options  correspond  to  the  options  available  in  the  DOMAIN 
clause  syntax  described  in  the  Form  Editor  User's  Manual. 

4.76.1  Calling  Format 

CALL  "SETDOM"  USING  FORM-NAME, 

ITEM-NAME, 

LENGTH, 

DOMAIN, 

RCODE . 

4.76.2  Parameter  Descriptions 


NAME  I/O  FORMAT  DEFINITION 


- 1 

FORM-NAME  | 

h - H 

Input 

jStr(10)  j The  name  of  the  containing  form 

ITEM-NAME 

Input 

Str ( 10) 

The  name  of  the  item  whose  dom¬ 
ain  you  want  to  define. 

LENGTH 

Input 

Num 

The  length  of  the  string  that 
contains  the  domain  options  in¬ 
cluding  separating  commas. 

DOMAIN 

Input 

Str 

(LENG) 

The  string  containing  the  dom¬ 
ain  options  separated  by  commas 

RCODE 

Output 

h- - 1 

Str  (  5) 

h - - 

The  routine  return  code.  The 
possible  values  are  defined  in 
the  include  member  FPCODE. 
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Valid  domain  options  are: 

LEFT 

RIGHT 

UPPER 

LOWER 

MUST  ENTER 
MUST  FILL 
NUMERIC 
MAXIMUM  int 
MINIMUM  int 

4.76.3  Example 

WORKING-STORAGE  SECTION. 

COPY  FPCODE  OF  IISSCLIB. 

COPY  FPPARM  OF  IISSCLIB. 

01  EXPFRM-NAME  PIC  X(10)  VALUE 

01  TSTFLD-NAME  PIC  X(10)  VALUE 

01  DOMAIN  PIC  X ( 6 )  VALUE  "NUMERIC". 
01  DOMAIN-LEN  PIC  S9(5)  COMP 

PROCEDURE  DIVISION. 


CALL  "SETDCM"  USING  EXPFRM-NAME, 
TSTFLD-NAME, 
DOMAIN-LEN, 

DOMAIN, 

RCODE . 

IF  RCODE  IS  EQUAL  TO  OK 


ELSE 

CALL  "PMSGLC"  USING  RCODE. 
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"EXPFRM" . 
"TSTFLD"  . 

VALUE  6. 
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4 . 77  SETDQN 

This  routine  sets  a  default  starting  place  for  identifying 
elements  in  the  current  Display  List  with  a  relative  qualified 
name.  Initially,  this  starting  place  is  the  form  PSCREN  at  the 
top  of  the  Display  List.  All  further  Form  Processor  relative 
qualified  names  will  be  relative  to  this  field  until  the  defauit 
is  reset  or  the  field  is  deleted. 

4.77.1  Calling  Format 

CALL  "SETDQN"  USING  QUALIFIED-NAME, 

RCODE . 

4.77.2  Parameter  Descriptions 


NAME  I/O  FORMAT  DEFINITION 


- H 

QUALIFIED- 

NAME 

h - H 

Input 

- | 

Str 

(1-120) 

The  qualified  name  that  identi¬ 
fies  the  default  starting  place 
in  the  Display  List  for  rela¬ 
tive  qualified  names. 

RCODE 

Output 

h - H 

Str (5) 

The  routine  return  code.  The 
possible  values  are  defined  in 
the  include  member  FPCODE. 

4.77.3  Example 

WORKING-STORAGE  SECTION. 

COPY  FPCODE  OF  IISSCLIB. 

COPY  FPPARM  OF  IISSCLIB. 

01  PATH-NAME  PIC  X(13)  VALUE  "WINDOW . FORM 1 . 
PROCEDURE  DIVISION. 


CALL  "SETDQN"  USING 
RCODE. 

IF  RCODE  IS  EQUAL  TO  OK 


PATH -NAME , 


ELSE 

CALL  "PMSGLC"  USING  RCODE. 
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4.78  SETHLP 


This  routine  defines  or  changes  the  help  information 
available  for  an  item  field.  The  routine  parameters  correspond  to 
the  components  of  the  HELP  clause  syntax  described  in  the  Form 
Editor  User's  Manual. 

4.78.1  Calling  Format 

CALL  "SETHLP"  USING  FORM-NAME, 

ITEM-NAME, 

TYPE, 

HELP, 

RCODE . 

4.78.2  Parameter  Descriptions 


NAME  I/O  FORMAT  DEFINITION 

+ - + - + - + - 


|  FORM-NAME  | Input  i 

Str(10)  j 

The  name  of  the  containing  form 

ITEM-NAME 

Input 

Str (10) 

The  name  of  the  item  field 
whose  help  information  you  want 
to  change  or  define. 

TYPE 

Input 

Str ( 10) 

A  character  to  specify  the  type 
of  help  being  defined.  Values 
are:  A  -  application,  F  -  form, 
and  S  -  string. 

HELP 

Input 

1 

Str 

(1-60) 

The  help  string  being  defined. 
Its  contents  depend  on  the  TYPE 
value.  When  TYPE  =  F,  HELP  con¬ 
tains  the  name  of  a  help  form; 
if  TYPE  =  A  it  is  ignored;  and 
if  TYPE  =  S  HELP  contains  the 
actual  help  string. 

RCODE 

4- - - 

Output 

h - - 

Str ( 5 ) 

i - 

The  routine  return  code.  The 
possible  values  are  defined  in 
the  include  member  FPCODE. 
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4.78.3  Example 

WORKING-STORAGE  SECTION. 

COPY  FPCODE  OF  IISSCLIB. 

COPY  FPPARM  OF  IISSCLIB. 

01  EXPFRM-NAME  PIC  X(10)  VALUE  " EXPFRM" . 

01  TSTFLD-NAME  PIC  X(10)  VALUE  "TSTFLD" . 

01  HELP-TYPE  PIC  X(l)  VALUE  "S". 
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01  HELP-MSG  PIC  X ( 60 ) 

VALUE  "SAMPLE  HELP  MESSAGE". 

PROCEDURE  DIVISION. 


CALL  "SEL'HLP"  USING  EXPFRM-NAME , 
TSTFLD-NAME , 

HELP-TYPE, 

HELP-MSG, 

RCODE . 

IF  RCODE  IS  EQUAL  TO  OK 


ELSE 

CALL  " PMSGLC"  USING  RCODE. 
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4 . 79  SETLDV 

This  routine  sets  display  parameters  (row,  col,  width  and 
depth)  for  a  logical  device  belonging  to  an  application.  If  the 
logical  device  is  not  opened  SETLDV  will  return  an  NFPDSTRC  error. 


4.79. 


Calling  Format 


CALL  "SETLDV"  USING  LDWNID, 

DSPROW, 

DSPCOL , 

DSPWDTH , 

DSPDPTH , 

RCODE . 


4.79.2  Parameter  Description 


NAME 

I/O 

FORMAT 

DEFINITION 

|  LDWNID 

| Input 

|  Mum 

| The  id  of  the  logical  device 

DSPROW 

Input 

Num 

j The  row  position  of  the  origin 
] of  the  logical  device  display. 

|  DSPCOL 

Input 

Num 

The  column  position  of  the  ori¬ 
gin  of  the  logical  device  dis¬ 
play. 

1  LSPWDTH 

1 

1 

Input 

Num 

| The  width  of  the  logical 
device's  display. 

DSPDPTH 

| Input 

1 

Num 

The  depth  of  the  logical 
device's  display. 

RCODE 

g - 

| Output 

— i - 

St r  (  5 ) 

4- - 

j The  routine  return  code.  The 
possible  values  are  defined  in 
the  include  member  FPCODE. 

4  -  1  9  1 
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3  Example 

WORKING-STORAGE  SECTION. 
COPY  FPCODE  OF  IISSCLIB. 
COPY  FPPARM  OF  IISSCLIB. 
PROCEDURE  DIVISION. 


CALL  "SETLDV"  USING  LDWNID, 
DSPROW , 

DSPCOL, 

DSPWDTH , 

DSPDPTH , 

RCODE . 

IF  RCODE  IS  EQUAL  TO  OK 


ELSE 

CALL  " PMSGLC"  USING  RCODE. 
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4.80  SETLOC 


This  routine  defines  the  position  of  a  field  on  a  form.  The 
routine  parameters  correspond  to  the  components  of  the  Location 
syntax  described  in  the  Form  Editor  User's  Manual. 


4.80.1  Callinq  Format 


CALL  "SETLOC"  USING  FORM-NAME, 

FIELD-NAME, 

VREL-FIEL, 

VEXTREF, 

VINTREF, 

ROW, 

HREL-FIELD , 

HEXTREF, 

HINTREF, 

COLUMN, 

RCODE . 


4.80.2  Parameter  Descriptions 


NAME  I/O  FORMAT  DEFINITION 

+  ~ — >  —  —  —  —  —  —  —  —  +  —  —  —  — '  —  — — b  —  — - - - — - -“  —  4- 

| FORM-NAME  | Input  |Str(10)|The  name  of  the  containing  form| 

-k —  —  —  —  —  —  —  —  —-f  —  —  j - 1 —  — - —  —  — - — - b 

FIELD-NAME  Input  Str(10)  The  name  of  the  field  whose 

position  you  want  to  define. 

—  —  —  —  —  —  _  —  —  —  —  —  — - 1 — b  — - — — — - - - b 
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- -1 

h - H 

h - H 

VREL- 

Input 

Str 

The  qualified  name  of  the  field 

FIELD 

(120) 

that  FIELD-NAME's  position  is 

vertically  relative  to  or  blank 

if  it  is  relative  to  its  con- 

i- - 

i- - 

taining  form. 

VEXTREF 

Input 

Num 

The  vertical  reference  point 
on  VREL-FIELD  that  FIELD-NAME's 
position  is  relative  to.  Values 
are:  1  -  top,  2  -  center,  and 

3  -  bottom. 

VINTREF 

Input 

Num 

The  vertical  reference  point  of 
FIELD-NAME  that  its  position  is 
relative  to.  Values  are  the 
same  as  for  VEXTREF. 

ROW 

Input 

Num 

The  number  of  rows  that  FIELD- 
NAME's  position  is  offset  from 
VREL-FIELD' s  reference  point. 

HREL- 

FIELD 

Input 

Str 

(1-120) 

The  qualified  name  of  the  field 
that  FIELD-NAME's  position  is 
horizontally  relative  to  or 
blank  if  it  is  relative  to  its 
containing  form. 

HEXTREF 

Input 

Num 

The  horizontal  reference  point 
on  HREL-FIELD  that  FIELD-NAME's 
position  is  relative  to.  Values 
are:  1  -  left,  2  -  center,  and 

3  -  right. 

HINTREF 

Input 

Num 

The  horizontal  reference  point 
of  FIELD-NAME  that  the  position 
is  relative  to. 

Values  the  same  as  for  HEXTREF. 

COLUMN 

Input 

Num 

The  number  of  columns  the  field 
is  offset  from  HREL-FIELD' s 
reference  point. 

+ - + - + - + - + 
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+ - + - + - + - + 

RCODE  Output  Str(5)  The  routine  return  code.  The 

possible  values  are  defined  in 
the  include  member  FPCODE. 

+ - + - + - + - + 


4.80.3  Example 


WORKING-STORAGE  SECTION. 
COPY  FPCODE  OF  IISSCLIB. 
COPY  FPPARM  OF  IISSCLIB. 


01 

EXPFRM-NAME 

PIC 

X(10) 

VALUE 

"EXPFRM" . 

01 

NEWFLD-NAME 

PIC 

xr  io) 

VALUE 

"NEWITEM" 

01 

REF-FLD-NAME 

PIC 

X  (7 ) 

VALUE 

"TSTFLD ; " . 

01 

TOP-LEFT-REF 

PIC 

S9(5) 

COMP 

VALUE  1. 

01 

CENTER-REF 

PIC 

S9(5) 

COMP 

VALUE  2. 

01 

BOT-RIGHT-REF 

PIC 

S9  ( 5 ) 

COMP 

VALUE  3 . 

01 

ZERO-COMP  PIC 

S9  ( 5 ) 

COMP  VALUE  0. 

01 

TWO-COMP  PIC 

S9  ( 5 ) 

COMP  VALUE  2. 

PROCEDURE  DIVISION. 


CALL  "SETLOC"  USING  EXPFRM-NAME , 
NEWFLD-NAME , 
REF-FLD-NAME , 
BOT-RIGHT-REF, 
TOP-RIGHT-REF, 

TWO -COMP, 

REF-FLD-NAME, 

CENTER-REF, 

CENTER-REF, 

ZERO-COMP, 

RCODE. 

IF  RCODE  IS  EQUAL  TO  OK 


ELSE 

CALL  "PMSGLC"  USING  RCODE. 
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4.81  SETNAM 


This  routine  renames  a  field  on  a  form. 

4.81.1  Calling  Format 

CALL  "SETNAM"  USING  FORM-NAME, 

OLD-NAME, 

NEW-NAME, 

RCODE . 

4.81.2  Parameter  Descriptions 

NAME  I/O  FORMAT  DEFINITION 

+ - + - + - + - + 


FORM-NAME 

Input 

Str(10) 

The  name  of  the  containing  form 

OLD-NAME  | Input 

Str (10) 

The  current  name  of  the  field. 

NEW-NAME 

Input 

Str ( 10) 

The  new  name  you  want  the  field 
to  have. 

RCODE 

Output 

- 1 

Str (5) 

— 

The  routine  return  code.  The 
possible  values  are  defined  in 
the  include  member  FPCODE. 
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.81.3  Example 

WORKING-STORAGE  SECTION. 
COPY  FPCODE  OF  IISSCLIB. 
COPY  FPPARM  OF  IISSCLIB. 


01 

EXPFRM-NAME 

PIC 

X(10) 

VALUE 

"EXPFRM" . 

01 

TSTFLD-NAME 

PIC 

X(10) 

VALUE 

"TSTFLD" . 

01 

NEWFLD-NAME 

PIC 

X(10) 

VALUE 

"NEWFLD" . 

PROCEDURE  DIVISION. 


CALL  "SETNAM"  USING  EXPFRM-NAME, 
TSTFLD-NAME, 
NEWFLD-NAME , 

RCODE . 

IF  RCODE  IS  EQUAL  TO  OK 


ELSE 

CALL  "PMSGLC"  USING  RCODE. 


4-159 


UM  620344200 
30  September  1990 


SET PRO 


4.82  SETPRO 


This  routine  adds  a  prompt  to  a  form  or  a  field  at  a 
specified  position.  The  routine  parameters  that  specify  the 
prompt  position  correspond  to  the  components  of  the  Location 
syntax  described  in  the  Form  Editor  User's  Manual. 

4.82.1  Calling  Format 

CALL  "SETPRO"  USING  FORM-NAME, 

FIELD-NAME, 

LENGTH, 

TEXT, 

VREL-FIELD, 

VEXTREF, 

VINTREF, 

ROW, 

HREL-FIELD , 

HEXTREF, 

HINTREF, 

COLUMN, 

RCODE . 

4.82.2  Parameter  Descriptions 


NAME  I/O  FORMAT  DEFINITION 


FORM-NAME 

Input 

- - H 

Str(10) 

The  name  of  the  form  to  add  the 
prompt  to  or  the  containing 
form. 

FIELD-NAME 

Input 

Str ( 10) 

t 

The  name  of  the  field  to  add 
the  prompt  to  or  blank  if  the 
prompt  is  being  added  to  FORM- 
NAME. 

LENGTH 

Input 

Num 

The  actual  length  of  the  prompt 
text  to  be  added. 

TEXT 

Input 

L- - 

Str 
(LENG) 
h - 

The  prompt  text  to  be  added. 
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+ - 4 

VREL- 

FIELD 

- 4 

Input 

- -t 

Str 

(1-120) 

The  qualified  name  of  the  field 
that  the  prompt  is  vertically 
relative  to  or  blank  if  it  is 
relative  to  its  containing  form 

VEXTREF 

Input 

Num 

The  vertical  reference  point 
on  VREL-FIELD  that  the  prompt 
position  is  relative  to.  Values 
are:  1  -  top,  2  -  center,  and 

3  -  bottom. 

VINTREF 

Input 

Num 

The  vertical  reference  point  of 
the  prompt  that  its  position  is 
relative  to.  Values  are  the 
same  as  for  VEXTREF. 

ROW 

Input 

Num 

The  number  of  rows  the  prompt's 
position  is  offset  from 
VREL-FIELD' s  reference  point. 

HREL- 

FIELD 

Input 

Str 

(1-120) 

The  qualified  name  of  the  field 
that  the  prompt's  position  is 
horizontally  relative  to  or 
blank  if  it  is  relative  to  its 
containing  form. 

HEXTREF 

Input 

Num 

The  horizontal  reference  point 
of  the  prompt  that  its  position 
is  relative  to.  Values  are: 

1  -  left,  2  -  center,  and  3  - 
right . 

HINTREF 

Input 

Num 

The  horizontal  reference  point 
of  the  prompt  that  the  position 
is  relative  to. 

Values  the  same  as  for  HEXTREF. 

COLUMN 

Input 

Num 

The  number  of  columns  the 
prompt  is  offset  from  HREL- 
FIELD's  reference  point. 

RCODE 

4- - —  —  —  —  —  —  — - 1 

Output 

Str (5) 

The  routine  return  code.  The 
possible  values  are  defined  in 
the  include  member  FPCODE. 
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WORKING-STORAGE  SECTION. 

COPY  FPCODE  OF  IISSCLIB. 

COPY  FPPARM  OF  IISSCLIB. 

01  EXPFRM-NAME  PIC  X(10)  VALUE  "EXPFRM" . 

01  TSTFLD-NAME  PIC  X(10)  VALUE  "TSTFLD" . 

01  PROMPT-TEXT  PIC  X(10)  VALUE  "NEW  PROMPT". 

01  PROMPT-LEN  PIC  S9(5)  COMP  VALUE  10. 

01  REFFLD-NAME  PIC  X(7)  VALUE  "TSTFLD:'. 

01  TOP-LEF-REF  PIC  S9(5)  COMP  VALUE  1. 

01  CENTER-REF  PIC  S9(5)  COMP  VALUE  2. 

01  BOT-RIGHT-REF  PIC  S9(5)  COMP  VALUE  3. 

01  ZERO-COMP  PIC  S9 ( 5 )  COMP  VALUE  0. 

01  TWO-COMP  PIC  S9 ( 5 )  COMP  VALUE  2. 

PROCEDURE  DIVISION. 


CALL  "SETPRO"  USING  EXPFRM-NAME, 
TSTFLD-NAME, 
PROMPT-LEN, 
PROMPT-TEXT, 
REFFLD-NAME, 
TOP-LEFT-REF, 
BOT-RIGHT-REF, 
TWO-COMP, 

REFFLD-NAME, 

DENTER-REF, 

ZERO-COMP, 

RCODE . 

IF  RCODE  IS  EQUAL  TO  OK 


ELSE 

CALL  "PMSGLC"  USING  RCODE. 
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4.83  SETSIZ 


This  routine  allows  you  to  specify  the  size  of  a  field. 

4.83.1  Calling  Format 

CALL  "SETSIZ"  USING  FORM-NAME, 

FIELD-NAME, 

WIDTH, 

HEIGHT, 

RCODE. 

4.83.2  Parameter  Descriptions 

NAME  I/O  FORMAT  DEFINITION 

+■ - + - + - + - + 


|  FORM-NAME  j Input  |Str(10)  | The  name  of  the  containing  form 

FIELD-NAME 

Input 

Str ( 10) 

The  name  of  the  field  whose 
size  you  want  to  specify. 

WIDTH 

Input 

Num 

The  number  of  columns  wide  the 
field  is. 

HEIGHT 

Input 

Num 

The  number  of  rows  high  the 
field  is. 

RCODE 

Output 

Str (5) 

The  routine  return  code.  The 
possible  values  are  defined  in 
the  include  member  FPCODE. 

+ - + - + - + - + 
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WORKING-STORAGE  SECTION. 

COPY  FPCODE  OF  IISSCLIB. 

COPY  FPPARM  OF  IISSCLIB. 

01  EXPFRM-NAME  PIC  X(10)  VALUE  "EXPFRM" . 

01  TSTFLD-NAME  PIC  X(10)  VALUE  "TSTFLD" . 

01  NEW-WIDTH  PIC  S9(5)  COMP  VALUE  20. 

01  NEW-HEIGHT  PIC  S9(5)  COMP  VALUE  1. 

PROCEDURE  DIVISION. 


CALL  "SETSIZ"  USING  EXPFRM-NAME, 

TSTFLD-NAME, 

NEW-WIDTH, 

NEW-HEIGHT, 

RCODE . 

IF  RCODE  IS  EQUAL  TO  OK 


ELSE 

CALL  " PMSGLC"  USING  RCODE. 
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4 . 84  SETTYP 

This  routine  allows  you  to  change  a  field's  type  on  all 
instances  of  an  open  form. 

4.84.1  Calling  Format 

CALL  "SETTYP"  USING  FORM-NAME, 

FIELD-NAME, 

NEW-TYPE, 

RCODE . 

4.84.2  Parameter  Descriptions 


NAME  I/O  FORMAT  DEFINITION 


FORM-NAME  | Input  |Str(10) | The  name  of  the  containing  form 

FIELD-NAME 

Input  j 

t 

Str (10) 

The  name  of  the  field  whose 
type  you  want  to  change. 

NEW-TYPE 

Input 

Str(l) 

A  character  code  to  specify  the 
field's  new  type.  Values  are: 

W  -  window,  F  -  form,  and  I  - 
item. 

RCODE 

Output 

H - 

Str (5) 

t- - 

The  routine  return  code.  The 
possible  values  are  defined  in 
the  include  member  FPCODE. 
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3  Example 

WORKING-STORAGE  SECTION. 

COPY  FPCODE  OF  IISSCLIB. 

COPY  FPPARM  OF  IISSCLIB. 

01  EXPFRM-NAME  PTC  X(10)  VALUE  "EXPFRM" . 

01  TSTFLD-NAME  PIC  X(10)  VALUE  "TSTFLD" . 

01  NEW-TYPE  PIC  X  VALUE  "W" . 

PROCEDURE  DIVISION. 


CALL  "SETTYP"  USING  EXPFRM-NAME, 
TSTFLD-NAME, 

NEW-TYPE, 

RCODE . 

IF  RCODE  IS  EQUAL  TO  OK 


ELSE 

CALL  "PMSGLC"  USING  RCODE. 
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4 . 85  SETVAL 

This  routine  allows  you  to  define  a  value  expression  for  an 
item  field.  This  expression  corresponds  to  the  Expression 
component  in  the  VALUE  clause  syntax  described  m  the  Form  Editor 
User's  Manual. 

4.85.1  Calling  Format 

CALL  "SETVAL"  USING  FORM-NAME, 

ITEM-NAME, 

LENGTH, 

EXPRESSION, 

RCODE . 

4.85.2  Parameter  Descriptions 

NAME  I/O  FORMAT  DEFINITION 

4-  — —  ■—-*  +  —  —  —  —  —  —  4“  —  - t* — — - h 

| FORM-NAME  | Input  |Str(10)|The  name  of  the  containing  form| 


b - H 

ITEM-NAME 

h - H 

Input 

h - H 

Str ( 10) 

The  name  of  the  item  field 
whose  value  expression  you  want 
to  define. 

LENGTH 

Input 

Num 

The  length  of  the  string  that 
contains  the  value  expression. 

EXPRESSION 

Input 

Str 

(LENG) 

The  string  containing  the 
value  expression. 

RCODE 

Output 

Str (5) 

The  routine  return  code.  The  1 

possible  values  are  defined  in 
the  include  member  FPCODE. 


+ - + - + - + - + 
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3  Example 


WORKING-STORAGE  SECTION. 
COPY  FPCODE  OF  IISSCLIB. 
COPY  FPPARM  OF  IISSCLIB. 


01 

EXPFRM-NAME 

01 

TSTFLD-NAME 

01 

VALUE -TXT. 

05  FILLER  PIC 

X 

05  FILLER  PIC 
05  FILLER 

X  ( 13 ) 

01 

VALUE-LEN  PIC 

S9  ( 5 ) 

PROCEDURE  DIVISION 

PIC  X(10)  VALUE  "EXPFRM". 
PIC  X(10)  VALUE  "TSTFLD" . 

VALUE  QUOTE. 

VALUE  "INITIAL  VALUE". 

PIC  X  VALUE  QUOTE. 

COMP  VALUE  15. 


CALL  "SETVAL"  USING  EXPFRM-NAME , 
TSTFLD-NAME, 

VALUE -LEN, 

VALUE -TXT, 

RCODE . 

IF  RCODE  IS  EQUAL  TO  OK 


ELSE 

CALL  "PMSGLC"  USING  RCODE. 
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4.86  TERMFP 


This  routine  is  used  to  exit  the  FP.  TERMFP  must  be  called 
to  return  terminal  characteristics  to  the  settings  they  were  at 
before  entering  the  FP. 

4.86.1  Calling  Format 
CALL  "TERMFP". 

4.86.2  Parameter  Descriptions 
NONE. 

4.86.3  Example 

WORKING-STORAGE  SECTION. 

PROCEDURE  DIVISION. 

CALL  " INITFP" . 


CALL  "TERMFP". 
EXIT-PROGRAM. 
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4.87  TERMVT 


This  routine  clears  the  VTI  mode  flag. 

4.87.1  Calling  Format 

CALL  "TERMVT"  USING  RCODE. 

4.87.2  Parameter  Descriptions 

NAME  I/O  FORMAT  DEFINITION 


H - (- 

The  routine  return  code.  The 
possible  values  are  defined  in 

the  include  member  FPCODE. 

.+ - 


RCODE 


Output 


Str (5) 


4.87.3  Example 

WORKING-STORAGE  SECTION. 
COPY  FPCODE  OF  IISSCLIB. 
COPY  FPPARM  OF  IISSCLIB. 
PROCEDURE  DIVISION. 


CALL  "INITVT"  USING  RCODE. 
IF  RCODE  IS  EQUAL  TO  OK 


CALL  "TERMVT"  USING  RCODE 
IF  RCODE  IS  EQUAL  TO  OK 
NEXT  SENTENCE 
ELSE 

CALL  "PMSGLC"  USING  RCODE 

ELSE 

CALL  "PMSGLC"  USING  RCODE. 
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SECTION  5 
INCLUDE  FILES 


The  FP  routines  use  the  include  files  FPPARM  and  FPCODE. 

The  symbol  IISSCLIB  points  to  the  location  containing  these  files. 
The  following  sections  list  the  information  defined  in  the  files. 

5.1  FPPARM 

The  values  for  various  constant  data  fields  used  by  the  FP 
routines  are  initialized  in  this  include  file.  These  data  fields 


Instances 

62 ; 1 ; 2 ; 6 ; 7 ; 8 ; 9c  CURRNT  -  The  value  to 

identify  the  current  instance  of  user  entered  data. 

PREV  -  The  value  to  identify  the  previous  instance  of  user 

entered  data . 

Window  Names 

SCREN  -  The  value  to  identify  the  top  window  of  the  Display 
List. 


Foreground  Attributes 


INP  -  The  value  for  the  INPUT  attribute  that  specifies  that 

the  user  may  enter  data  for  this  item  and  the  value  will 
be  echoed  on  the  screen.  The  user  may  tab  to  this  item. 


OUTP  -  The  value  for  the  OUTPUT  attribute  that  specifies  that 

only  the  application  program  may  enter  data  for  this 
item . 


HIDDEN  -  The  value  for  the  HIDDEN  attribute  that  specifies  that 
the  user  may  enter  data  for  this  item  but  the  value  will 
not  be  echoed  on  the  screen. 


ERR  -  The  value  for  the  ERROR  attribute  that  causes  the  item 

to  be  highlighted  when  displayed  on  the  screen  (e.g., 
the  item  will  blink).  The  user  may  enter  data  for  this 
item  and  the  value  will  be  echoed  on  the  screen.  This 
attribute  may  only  be  set  as  a  temporary  attribute.  It 
is  useful  for  showing  the  user  which  items  have  errors 
in  them. 


GUARDED  -  The  value  for  the  GUARDED  attribute  that  specifies 

that  only  the  application  program  may  enter  a  value  tor 
this  item.  The  value  is  displayed  in  bold  on  terminals, 
that  support  bold. 
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TXT 

CALC 

TBFLD 

Function  j 
HELPKEY 

QUITKEY 

ENTERKEY 

LSCRLKEY 

RSCRLKEY 

USCRLKEY 

DSCRLKEY 

LPAGEKEY 

RPAGEKEY 

UPAGEKEY 

DPAGEKEY 


-  The  value  for  the  TEXT  attribute  that  specifies  that 
only  the  application  program  may  enter  a  value  for  this 
item.  The  value  is  not  in  bold. 

-  The  value  for  the  CALCULATED  attribute  that  specifies 
that  only  the  Form  Processor  may  enter  a  value  for  this 
item.  The  value  is  displayed  in  bold. 

-  The  value  for  the  TABFLD  attribute  that  specifies  that 
only  the  application  program  may  enter  a  value  for  this 
item  but  the  user  may  tab  to  the  item. 

:eys 


-  The  number  of  the  terminal  control  key  that  the  user 
can  press  to  display  additional  information  or  an 
explanation  of  the  data  to  be  entered  for  a  form  or  form 
field . 

-  The  number  of  the  terminal  control  key  that  the  user 
can  press  to  end  data  entry  and  bypass  edit  checks. 

-  The  number  of  the  terminal  control  key  that  the  user 
can  press  to  end  data  entry  and  return  control  to  the 
application. 

-  The  number  of  the  terminal  control  key  that  the  user 
can  press  in  "scrll/page"  mode  to  horizontally  scroll 
the  data  on  the  screen  to  the  left. 

-  The  number  of  the  terminal  control  key  that  the  user 
can  press  in  "scrll/page"  mode  to  horizontally  scroll 
the  data  on  the  screen  to  the  right. 

-  The  number  of  the  terminal  control  key  that  the  user 
can  press  in  "scrll/page"  mode  to  vertically  scroll  the 
data  on  the  screen  up. 

-  The  number  of  the  terminal  control  key  that  the  user 
can  press  in  "scrll/page"  mode  to  vertically  scrol 1  the 
data  on  the  screen  down. 

-  The  number  of  the  terminal  control  key  that  the  user 
can  press  in  "scrll/page"  mode  to  horizontally  page  the 
data  on  the  screen  to  the  left. 

-  The  number  of  the  terminal  control  key  that  the  user 
can  press  in  "scrll/page"  mode  to  horizontally  page  the 
data  on  the  screen  to  the  right. 

-  The  number  of  the  terminal  control  key  that  the  user 
can  press  in  "scrll/page"  mode  to  vertically  page  the 
data  on  the  screen  up. 

-  The  number  of  the  terminal  control  key  that  the  user 
can  press  in  "scrll/page"  mode  to  vertically  page  the 
data  on  the  screen  down. 
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Background  Attributes 


BLACK 

-  The  attribute 
foreground . 

value 

for : 

black  background, 

wh  i  te 

WHITE 

-  The  attribute 
foreground . 

value 

for : 

white  background, 

white 

RED 

-  The  attribute 
foreground. 

value 

for : 

red  background,  white 

GREEN 

-  The  attribute 
foreground. 

value 

for: 

green  background, 

white 

YELLOW 

-  The  attribute 
foreground. 

value 

for : 

yellow  background,  white 

BLUE 

-  The  attribute 
foreground . 

value 

for : 

blue  background, 

white 

MAGENTA 

-  The  attribute 
foreground . 

value 

for: 

magenta  background,  white 

CYAN 

-  The  attribute 
foreground . 

value 

for : 

cyan  background, 

white 

Duration 

Attributes 

TEMP  -  The  value  for  the  attribute  type  "temporary". 


PERM  -  The  value  for  the  attribute  type  "permanent". 

NOTE:  The  FP  function  keys  mentioned  above  and  the  <ENTER>  key 

are  terminal  specific.  The  application  user  will  have 
to  be  given  this  information  based  on  the  type  of 
terminal  available  as  explained  in  the  IISS  Terminal 
Operator  Guide. 

5.2  FPCODE 


This  include  file  contains  the  routine  return  code  values. 
These  return  codes  indicate  irregular  use  of  the  FP  routines.  An 
application  can  display  messages  related  to  the  codes  in  the 
message  line  by  using  the  FP  routines  PMSGLC  and  PMSGLC.  A 
developer  testing  a  new  application  may  want  to  use  the  debug 
option  to  display  these  messages  without  calling  PMSGLC.  The 
debug  option  is  explained  in  the  Terminal  Operator  Guide.  The 
code  names  and  their  related  messages  are: 


Number  Name 


Message 


00000 

00001 

02000 


OK  (Blank  -  normal  completion) 

ALCERR  Memory  Allocation  Error 

FILOERR  File  open  error 
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02001 

FILNTFND 

File  not  found 

02002 

FILNTCRT 

File  not  created 

02003 

FILNTDEL 

File  not  deleted 

02004 

ENDOFFIL 

End  of  file 

02005 

FILNTOPN 

File  not  opened 

02006 

FILNTCLS 

File  not  closed 

02007 

FILRERR 

File  read  error 

02008 

FILWERR 

File  write  error 

02009 

FILNTIND 

File  not  indexed 

02010 

FILNTSEQ 

File  not  sequential 

07000 

MATH  ERRORS 

07001 

INTOVRr L 

Integer  overflow 

07002 

FLTOVRFL 

Floating  point  overflow 

07003 

ZERODIV 

Zero  Divide 

70300 

FORM  PROCESSOR  MESSAGES 

70301 

INVPAG 

Invalid  page  number 

70302 

FNOTFND 

Form  not  found 

70303 

FISOPEN 

Form  is  already  open 

70304 

FRMCYCLE 

Cyclic  reference  in  form  name 

70305 

OPNERR 

Open  error  -  Unable  to  read  form  definition 
file 

70306 

EXPERR 

Error  in  expression 

70307 

TRNCFLD 

Field  value  too  long  -  truncated 

70308 

UNKTYPE 

Internal  error  -  Unknown  field  type 

70309 

PNOTARY 

Qualified  name  is  not  an  array 

70310 

NILKEY 

Non-functional  key 

70311 

SYSERR 

System  error  -  Call  System  Administrator 

70312 

PBFULL 

Paste  buffer  full 

70313 

INVEDT 

Field  can  not  be  edited 

70314 

INVISIZ 

Items  must  be  fixed  in  size 

70315 

PAT HERR 

Invalid  path  name 

70316 

NOMACH 

String  not  found 

70317 

PNOTFND 

Path  not  found 

70318 

WRDWRAP 

Word  too  long  to  fit  between  fill  margins  - 
wrapped 

70319 

INVMRG 

Invalid  fill  margins 

70320 

PNOTUNQ 

Path  not  unique 

70321 

PNOTWIN 

Qualified  name  is  not  a  window 

70322 

FNOTOPN 

Form  is  not  open 

70423 

NOHELP 

No  help  available 

70324 

NOHLPFRM 

Error  opening  help  form 

70325 

BLKFLD 

Field  must  be  entered 

70326 

IMBBLK 

Field  must  not  contain  blanks 

70327 

NFLTDATA 

Field  must  contain  only  real  numbers 

70328 

N I NT DATA 

Field  must  contain  only  integer  numbers 

70329 

OUTRNG 

Field  value  is  out  of  range 

70330 

ATNOTFND 

Attribute  does  not  exist 

70331 

FINUSE 

Can  not  close  form  -  Form  is  in  use 

70332 

MFOPNERR 

Message  file  can  not  be  opened 

70333 

INVKEY 

Requested  function  can  not  be  performed  on 
this  screen 

70334 

INVIID 

Invalid  instance  ID 

70335 

NTMREJ 

Network  Transaction  Manager  (NTM)  reject 

70336 

MAPFAIL 

Virtual  terminal  buffer  format  error 

70337 

BUFOVFL 

Virtual  terminal  buffer  overflow 

70338 

GTCURERR 

GETCUR  could  not  build  fully  qualified  name 

70339 

PARSERR 

Level  specified  does  riot  exist 
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70340 

70341 

70342 

70343 

70344 

70345 

70346 

70347 

70348 

70349 

70350 

70351 

70352 

70353 

70354 

70355 

70356 

70357 

70358 

70359 

70360 

70361 

70362 

70363 

70364 

70365 

70366 

70367 

70368 

70369 

70370 

70371 

70372 

70373 

70374 

70375 

70376 

70377 

70378 

70379 

70380 

70381 

70382 

70383 


PNOTITEM 

OLDFORM 

ENDARY 

NOTSCROL 

PNOTBACK 

FILFRMMM 

APKEY 

INTADDER 

INDEB 

OUTDEB 

MSGRANGE 

INVRPT 

BADDEV 

BADAP 

BADAPS 

INVLDIM 

BFOVRFLW 

BFUNDFLW 

INTADLER 

INTGETER 

NTRMVER 

OLNCHG 

WNDNSEL 

UISWNNF 

SDPNDNG 

SDCNCLD 

INVRLFN 

NFPDSTRC 

NWNDIDFN 

BADFPD 

WNDSEL 

WMARCHSZ 

WMARCHLC 

SCPWNOPN 

SCPRNOPN 

SCPSNOPN 

SCPBADFL 

SCPSVERR 

SCPWRERR 

SCPRDERR 

OVRFLW 

BADDATA 

WNDUNSEL 

APNOTFND 


Qualified  name  not  an  item 

Old  form  definition  file  format  -  Recompile 

End  of  scrolling  section  reached 

Field  is  not  scrollable 

Qualified  name  not  a  window  or  form 

Form  name  does  not  match  form  definition 

file  name 

Function  key  is  to  be  processed  by  application 
Internal  error  -  Unable  to  add  form  to 
window 

In  debug  mode 
Out  of  debug  mode 

Message  number  specified  does  not  exist 

Invalid  repeat  count 

Unable  to  access  specified  device 

Unable  to  start  specified  application 

Unable  to  create  application  data  structures 

Invalid  dimension 

Data  will  not  fit  into  buffer  provided 
Not  enough  data  to  fill  the  buffer  provided 
Internal  Error  -  Could  not  add  element  to 
open-ended  array 

Internal  error  -  Unable  to  get  data  from  forms 
Internal  error  -  Unable  to  remove  form  from 
window 

Role  not  changed 

Window  not  selected 

UIS  window  not  found 

Shut  down  pending 

Shut  down  cancelled 

Invalid  role/ function 

No  FPD  Structure  found 

No  unused  window  ID  found 

Bad  logical  device  data  structure  -  (Bad 


FPD) 

Window  is  selected 
Cannot  change  size  of 
element  in  an  array 
Cannot  change  pos.  of 
element  in  an  array 
Script  file  could  not 
Script  file  could  not 
Script  output  save  fi 
for  writing 
Script  file  is  bad 
Could  not  write  to  sc 
close  save  file 
Could  not  write  to  sc 
scripting 

Could  not  read  script 
scripting  session 
Adding  an  element  wou 
form 

Non-printable  charact 
with  "?" 

Window  is  unselected 
Application  not  found 


window  which  is  an 
window  which  is  an 


be 

opened 

for  writing 

be 

opened 

for  reading 

le  could  not  be  opened 

r  ipt 

output 

save  file  - 

r  ipt 

file  - 

term i nat ing 

f  il 

e  -  terminating 

Id  e 

xceed  bounds  of 

ers 

in  data 

-  replaced 
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70384  CURFPDST  Cannot  remove  or  close  current  logical 

device  standalone 

70385  NINVTIMD  Not  in  Form  Processor  bypass  mode  (VTI  mode) 

70386  INVTIMD  In  Form  Processor  bypass  mode  (VTI  mode) 

70387  INTPUTER  Internal  Error  -  Could  not  put  data  into  field 

70388  INTPATER  Internal  Error  -  Could  not  charge  attribute 

for  a  field 

70389  GTNAMERR  Could  not  find  name 

70390  GTDQNERR  Could  not  find  default  qualified  name 

70391  AIVERORR  Wrong  version  of  Application  Interface  - 

Relink  application 

70392  NODEPVAL  No  dependent  value  clause  found 

70393  VALNTFND  Value  clause  not  found 

70394  FUNCNQ  Function  is  not  unique 

70395  NOFNCDEF  No  definition  of  function  in  UI  Database 

70386  ILTYPCNV  Illegal  type  conversion  in  value  clause 

70397  ILLGLNAM  Illegal  Name 

70398  DUPLCNAM  Duplicate  Name 

70399  FLDNTFND  Field  Not  Found 

70400  FORM  PROCESSOR  CODES  (CONTINUED) 

70401  ILLGLRFP  Illegal  reference  point 

70402  FLDNTARR  Field  is  not  an  array 

70403  INVALSEL  Invalid  command  selection 

70404  NOMORFLD  End  of  field  list 

70405  INVINDEX  Invalid  index  specified 

70406  MINMAXER  Minimum  cannot  be  greater  than  maximum 

70407  DOMNTFND  Domain  value  not  found 

70408  PMTNFND  Prompt  not  found 

70409  ARNOTFND  Array  not  found 

70410  HCYREF  Horizontal  cyclical  reference  in  field 

location 

70411  VCYREF  Vertical  cyclical  reference  in  field  location 

70412  iNOHREF  Horizontally  referenced  field  not  found 

70413  NOVREF  Vertically  referenced  field  not  found 

70414  OFFRIGHT  Field's  location  is  off  right  of  form 

70415  OFFLEFT  Field's  location  is  off  left  of  form 

70416  OFFTOP  Field's  location  is  off  top  of  form 

70417  OFFBOTTM  Field's  location  is  off  bottom  of  form 

70418  OVLPFLDS  Two  or  more  fields  or  prompts  overlap 

70419  TOONAROW  Fields  extend  off  form  to  the  right 

70420  TOOSHORT  Fields  extend  below  form 

70421  VALDEP  Other  fields  depend  on  this  field  for  their 

value 

70422  INVHLPTP  Invalid  help  type  -  must  be:  ( A) ppl icat ion , 

( F) orm ,  (S ) tring 

70423  FMTRUFLS  Flag  must  be  (T) rue  or  (F)alse 

70424  DOMNTCHR  Item's  domain  type  not  character 

70425  DOMNTINT  Item's  domain  type  not  integer 

70426  DOMNTFLD  Item's  domain  type  not  floating  point 

70427  PRMNTFND  Attribute  primitive  not  found 

70428  FRGNTFND  Foreground  color  not  found 

70429  BKGNTFND  Background  color  not  found 

70430  PRVFDFIL  FD  file  already  exists  :  specify  replace 

70431  PRVFDLFL  FDL  file  already  exists  :  specify  replace 

70432  NODEVICE  The  current  logical  device  has  no  physical 

device 

70433  NOTSLIN  Field  is  not  a  non-graphics  line 
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70434  NOLSTYL  No  display  style  defined  for  non-graphics  line 

70435  STYTRNC  Non-graphics  line  display  style  truncated 

70436  ILLGLLEN  Invalid  length  for  non-graphics  line  display 

style 

70437  PNOTFRM  Qualified  name  is  not  a  form 

70438  BDOFFSET  Window  offsets  must  be  positive  numbers 

79900  ERRORS  THAT  ARE  LOGGED 

79901  NTMINT  Bad  return  from  NETWORK  TRANSACTION  MANAGER 

(NTM)  INITEX  routine 

79902  NTMLOG  Bad  return  from  NTM  Logon  routine 

79903  NTMLO  Bad  return  from  NTM  Logoff  routine 

79904  BSEND  Bad  send  from  UI  to  AP 

79905  CROLER  Bad  return  from  NTM  CHGROL  routine 

79906  UOPFRM  Bad  return  from  open  form  routine 

79907  NTMMSGNA  NTM  message  not  accepted 

79908  NTMPRCNT  NTM  terminate  process  message  not  accepted 

79909  FPABORT  Form  Processor  ABORT 

79910  USRABRT  User  aborted 

79911  FLDTBIG  Field  too  big  to  be  sent  by  the  NTM  and  was 

truncated 
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SECTION  6 

ACCESSING  THE  FP  ROUTINES 


The  following  describes  the  environment  required  for  running 

the  IISS  User  Interface  (UI)  on  a  DEC  VAX  under  the  VMS  operating 

system . 

6 . 1  Logicals 

The  following  are  the  logical  symbols  required. 

IISSCLIB  -  Points  to  the  IISS  include  library  which  contains  all 
the  COBOL  include  files. 

I ISSFLIB  -  Points  to  the  directory  which  the  Form  Processor 

searches  second  for  FD  files  (form  definition).  It 
must  be  defined  at  the  JOB  level. 

IISSILIB  -  Points  to  the  directory  which  contains  the  source  for 
COBOL  include  files. 

IISSMLIB  -  Points  to  the  Form  Processor's  message  files.  It  must 
be  defined  at  the  JOB  level. 

IISSSLIB  -  Points  to  the  directory  which  contains  Form  Definition 
Language  (FDL)  source  files.  It  must  be  defined  at  the 
JOB  level. 

IISSULIB  -  Points  to  the  directory  which  the  Form  Processor 

searches  first  for  FD  (form  definition)  files.  It  must 
be  defined  at  the  JOB  level. 
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6 . 2  Linking 

The  following  are  the  object  libraries  for  linking  with  the 
Form  Processor  and  Virtual  Terminal. 

The  object  libraries  required  for  an  application  to  run  under 
IISS  are: 

uidir: [util ] utilolb/ i=sysmsg 
cdmdir : [fpai]fpaiolb/lib 
cdmdir: [ cdmr ] cdmolb/ 1 ib 
ntmdir: [services ] servolb/1 ib 
uidir: [util]utilolb/lib 
uidir: [clib] clibolb/1 ib 
uidir: [ ipc ] ipcolb/ 1 ib 
sys$ library : vaxcrtl/ 1 ib 

Note:  The  CDM  library  is  not  required  if  the  CC“  is  not  used. 

For  development  and  testing  purposes  a  version  f  the  NTM 
with  limited  capabilities  is  available.  It's  link  is  as  follows: 

uidir: [minintm]miniolb/lib 
uidir: [fpai]fpaiolb/lib 
uidir: [ util ] utilolb/1 
uidir: [ cl ib ] cl ibolb/1 ib 
uidir: [ ipc] ipcolb/lib 
sys$ library : vaxcrtl/1 ib 

For  development  and  testing  purposes  there  is  a  version  of 
the  Form  Processor  that  runs  as  a  standalone  operation  for 
applications  which  do  noi  require  the  NTM.  Use  the  following 
object  libraries: 

uidir: [ saf p ] saf polb/ 1 ib 

uidir: [util]utilolb/l/i=(sysmsg, fndmsg) 

uidir: [ fp] fpolb/1 ib/ i=prnf Id 

uidir : [ driver ] dr ivolb/ 1 ib/inc= (dddd , prnwnd) 

uidir: [ test ] testolb/ 1 ib 

uidir: [ cl ib ] cl ibolb/1 ib 

sys$l ibrary : vaxcrtl/ 1 ib 

where  'dddd'  is  the  appropriate  Device  Driver  (i.e.,  VT100, 
TEK4100,  or  IBM3270) . 
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SECTION  7 


SAMPLE  APPLICATION  PROGRAM 


This  is  the  "C"  source  code  for  the  Message  Management 
program  which  uses  the  FP  routines.  Figure  7-1  shows  the  form 
that  the  user  interfaces  with. 


Figure  7-1  Sample  Form 


/*  NAME 

*  MM  -  Message  Management 

*  Written:  14-FEB-1984  14:24:47 

*  Revised:  17-JUL-1985  10:54:01 

* 

*  SYNOPSIS 

*  main() 


-  JONES 


DESCRIPTION 

Utility  to  maintain  message  files  used  by  form  processor 


# include 
# include 
A  include 
# include 
# include 
# i nclude 
# include 


<stdtyp . h> 
<stdio . h> 

<  f pparm . h> 

<  f pd . h> 

<  f pcode . h> 

<  fpemsg . h  > 
<ntm . h> 


^define  F I LE_ FORMAT  " i issml ib : msg% 3 . 3s . msg" 
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#def ine  MSG_MAX  100 
#def ine  MSG_PAGE  10 

#define  ENTER  0 

#def ine  NEXTPAGE  5 
#def ine  PREVPAGE  6 
#def ine  FIRSTPAGE  7 
#def ine  LASTPAGE  8 

#def ine  CONNECT_ERR  "5" 

#def ine  PROGRAM_ERR  "4" 

#def ine  NORMAL_TERM  "1" 

char  myname[]  =  "SDMMZZZZZZ" ; 

# if ndef  STANDALONE 

int  nmsgfil  =  0; 

struct  msgfil  msgfil [NMSGFIL] ; 

#endif 

static  int  current  =  CURRNT; 

static  int  previous  =  PREV; 

static  MSGLIN  msgs [MSG_MAX ] ; 

static  FILE  *mmfp  =  NULL; 

static  bool  saveit(); 
static  void  newfile(); 
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main ( ) 

{ 

char 
char 
char 
char 
MSGLIN 
int 
int 
bool 
int 
char 
char 
char 
char 
static 

inital (buffer ,  bufsize,  &systate,  rcode); 

if  (memcmp (rcode ,  NTMGOODRET,  5)  !=  0)  trmnat ( CONNECTERR) ; 

trmstatus  =  PROGRAM_ERR; 
initfp ( ) ; 

opnfrm ( fname ,  rcode); 

if  (memcmp ( rcode ,  OK,  RCODE_LEN)  !=  0)  goto  error; 
addfrm (SCREN,  fname,  &page,  rcode) ; 

if  (memcmp ( rcode ,  OK,  RC0DE_LEN)  !=  0)  goto  error; 
prev_base[0]  =  1 \0 ' ;  /*  guaranteed  not  to 

match  what's  on  screen  */ 
memset(msgs,  1  ',  sizeof  msg2); 

for  (;;) 

l 

oiscr (SCREN,  &pfkey,  rcode) ; 

if  (memcmp (rcode,  OK,  RCODE_LEN)  !=  0)  goto  error; 
if  (pfkey  ==  QUITKEY)  break; 

gdata ( &current ,  "SCREEN . MM. MBASE" ,  base,  rcode); 
if  (memcmp (rcode,  OK,  RCODE^LEN)  !=  0)  goto  error; 
memcpy(msg2,  msgs+curlin,  sTzeof  msg2); 

gdata (Scurrent ,  "SCREEN . MM. MSGLIN" ,  msgs+curlin,  rcode) ; 
if  (memcmp ( rcode ,  OK,  RCODE_LEN)  !=  0)  goto  error; 
changed  =  changed  I |  memcmp (msgs+curl in ,  msg2 , 
sizeof  msg2)  !=  0; 

if  (memcmp (base ,  prev_base,  sizeof  base)  !=  0) 

/*  new  base  entered  */ 

{ 

if  (changed)  pmsgls ( "Changes  NOT  saved") ; 
newf ile (f iledesc,  base); 
curl in  =  0; 
changed  =  FALSE; 


rcode  [RCODE__LEN]  ; 
base [ 5]  ; 
prev_base [ 5]  ; 
f iledesc [30] ; 
msg2 [MSG_PAGE] ; 
page  ; 
pfkey; 

changed  =  FALSE; 
curl in  =  0; 
buffer[4096] ; 
*bufsize  =  "4096"; 
systate ; 

*trmstatus ; 
cl)ar  fname  [1  =  "MM 
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memcpy (prev_base ,  base,  sizeof  prev_base) ; 
continue; 

) 

switch  (pfkey) 

{ 

case  ENTER: 

if  (changed  &&  saveit ( f iledesc) ) 

{ 

pmsgls ( "Changes  saved"); 
changed  =  FALSE; 

> 

else  if  (changed)  pmsgls ( "Changes  NOT  saved"); 

else  pmsgls ("No  changes  made"); 

break; 

case  NEXTPAGE: 

if  (curlin  +  MSG_PAGE  <  MSG_MAX)  curlin  +=  MSG_PAGE ; 
goto  redisplay; 
case  PREVPAGE : 

if  (curlin  >=  MSG_PAGE)  curlin  -=  MSG_PAGE; 
goto  redisplay; 
case  FIRSTPAGE: 
curlin  =  0; 
goto  redisplay; 
case  LASTPAGE: 

while  (curlin  +  MSG_PAGE  <  MSG_MAX  && 

memcmp (msgs [ curl in  +  MSG_PAGE-1 ] . name , 

"  ",  8)  !=  0) 
curlin  +=  MSG_PAGE; 
redisplay : 

pdata ( "SCREEN. MSGLIN" ,  msgs  +  curlin,  rcode) ; 

if  (memcmp ( rcode ,  OK,  RCODE_LEN)  !=  0)  goto  error; 

break; 

) 

> 

trmstatus  =  NORMALTERM; 
error: 

termfp ( ) ; 

trmnat (trmstatus) ; 

) 

bool  saveit ( f iledesc) 
char  f iledesc [ ] ; 

( 

register  int  n; 

FILE  *mmfp2 ; 
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if  ( I (mmfp2  =  f open ( f iledesc ,  "w")))  return  FALSE; 
for  (n  =  MSG_MAX;  n  >  0  &&  memcmp (msgs [ n  -  1] .name, 

"  ",  8)  ==  0; 

n— ) 

t 

n  -=  fwrite(msgs,  sizeof  (MSGLIN) ,  n,  mmfp2) ; 
return  ( fclose (mmfp2 )  ==  0  &&  n  ==  0); 

} 

static  void  newfile ( f iledesc ,  base) 
char  filedesc[],  base[ ] ; 

{ 

register  int  num,  i; 

char  rcode [RC0DE_LEN] ,  charnum[6]; 

memset(msgs,  '  1 ,  sizeof  msgs); 

for  (i  =  0,  num  =  0;  i  <  3;  i++) 
num  =  num* 10  +  base[i]-'0'; 
num  *=  100; 

sprintf ( f iledesc,  FILE_FORMAT,  base); 
if  ((mmfp  =  fopen( f iledesc,  "r"))  !=  NULL) 

{ 

fread(msgs,  sizeof  (MSGLIN),  MSGMAX,  mmfp); 
fclose (mmfp) ; 

> 

for  (i  =  0;  i  <  MSG_MAX ;  i++) 

( 

sprintf (charnum,  "%5d",  num+i); 

memcpy (msgs [ i ]. number ,  charnum,  sizeof  msgs [ 0 ]. number) ; 

l 

pdata ("SCREEN. MM. MSGLIN" ,  msgs,  rcode); 

) 
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SECTION  8 

Layout  Optimization  System 


8 . 1  Description 

The  Layout  Optimization  System  provides  the  user  with  an  easy 
method  of  designing  and  creating  charts,  either  to  the  user's 
specifications  or  to  default  specifications  using  objects  and 
relationships  defined  by  the  user. 

8.1.1  Getting  Started 

In  order  to  help  the  user  define  and  print  charts,  the  Layout 
System  needs  very  specific  inputs  from  the  user.  It  also  uses 
some  specialized  terminology  to  refer  to  these  inputs. 

An  archetype  is  a  template,  or  prototype.  A  chart  archetype 
is  a  generic  structure  that  you  may  want  several  of  your  specific 
charts  to  follow.  An  object  archetype  is  a  generic  template  which 
you  may  use  for  several  different  objects. 

An  icon  is  an  instance  of  a  symbol  used  on  a  chart. 

A  chart  instance  is  a  specific  chart.  An  object  instance  is 
a  specific  chart.  Using  this  terminology,  a  chart  archetype  might 
have  several  chart  instances  which  use  it,  or  an  object  archetype 
might  have  several  object  instances  which  use  it. 

Consider  the  following  example  chart: 
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Semester/ 17 

+ - + 

| Semester  No . | 

+ - + 

Start  Date 


+  - 


is  implemented  by 


Of  f ering/ 18 

+ - + 

| Course  Code  | 
+ - + 


*  P 

Section/24 

+ - 

Course  Code 
Semester  No. 
Section  No. 


■+ 


Course/ 16 

+ - + 

| Course  Code  | 

+ - + 

Course  Name 


teaches 


P 


Ful 1 t ime/ 18 

- 1 

Instructor  IDj 


++--+■ 


Instrctr/14 


Instructor  ID  I  Instructor 


Inst.  Name 


Type 


Salary 


Parttime/24 

+ - + 

| Instructor  ID ] 

+-\ - h - + 

Hourly  Rate 


Figure  8-1  Sample  Chart 

In  order  to  use  the  Layout  System  to  draw  and/or  change  this 
chart,  you  need  to  create  a  form  for  each  different  type  of  symbol 
appearing  on  the  chart.  This  process  will  create  a  template,  or 
"archetype"  for  the  symbol.  The  Layout  system  will  use  that  form 
to  create  the  symbol  each  time  it  is  needed  on  the  chart. 
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The  above  chart  contains  five  different  types  of  symbols. 
There  are  two  different  object  types  appearing  on  the  chart  (one 
with  keys  and  one  without),  two  different  termination  symbols  (* 
and  *  P)  ,  and  one  categorizat ion  symbol.  (Termination  symbols  anti 
categorization  symbols  are  not  required  by  the  Layout  System. 

They  are  optional,  to  use  only  if  your  particular  chart  needs 
them.  ) 

The  first  step  towards  using  the  Layout  System  is  to  create  a 
form  for  each  different  type  of  symbol  your  chart  needs.  On  each 
of  those  forms,  you  are  going  to  "draw"  one  of  the  symbols  using 
the  "stretchy  lines"  provided  by  the  User  Interface  (the  syntax 
for  using  "stretchy  lines"  is  found  in  the  Form  Editor  User's 
Manual) .  You  do  not  place  text  in  the  symbol.  You  use  an  item 
field  on  the  form  to  reserve  space  for  the  text.  The  Layout 
System  will  take  care  of  entering  the  text  for  you.  For  example, 
the  form  to  define  the  type  of  symbol  used  by  the  "Offering"  and 
"Section"  objects  might  look  like  this: 

+ - - + 


+ - +  +--+ 


Figure  8-2  Sample  Object  Archetype  Definition  Form 

The  first  two  blocks  on  the  form  are  the  item  fields  into 
which  the  name  of  the  object  and  the  object  number  will  be  placed. 
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The  large  block  is  drawn,  either  using  the  "stretchy  lines" 
provided  by  the  User  Interface  (syntax  is  defined  in  the  Form 
Editor  User's  Manual),  or  by  using  text  characters  (dashes, 
vertical  bars,  underlines,  etc.)-  It  is  not  recommended  that  text 
characters  be  used.  The  Layout  System  may  need  to  resize  some  of 
the  symbols  you  have  defined  when  printing  the  chart.  Stretchy 
lines  can  be  resized,  text  characters  cannot.  This  may  result  in 
gaps  or  overruns  in  a  chart  which  uses  text  characters  rather  than 
stretchy  lines. 

The  three  smaller  blocks  within  the  large  one  are  also  item 
fields,  into  which  the  names  of  data  fields  required  by  the  object 
are  placed  by  the  Layout  System. 

The  two  termination  symbols  used  on  the  example  chart  are 
and  "*  P" .  A  separate  form  must  be  created  for  each  of  these 
symbols.  This  is  done  in  the  same  manner  as  the  object  symbols 
are  defined.  An  example  might  look  like  this: 

+ - + 

*  P  ! 


i 

t 

i 


+ - + 

Figure  8-3  Sample  Termination  Symbol  Archetype  Definition  Form 
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Notice  that  the  "*  P"  symbol  appears  after  the  relationship 
"is  implemented  by",  but  after  the  "teaches"  relationship  it 
appears  as  "* 

P" .  The  form  illustrated  above  can  be  used  to 
represent  both  of  these.  The  Layout  System  can  rotate  symbols  so 
that  they  can  fit  into  any  context. 

In  the  same  way  as  the  object  and  termination  symbols  were 
defined,  the  categorization  symbol  must  also  be  defined  on  a  form. 
Once  every  different  type  of  symbol  you  plan  to  use  on  your  chart 
has  been  defined  on  a  form,  you  are  ready  to  start  using  the 
Layout  System. 

There  are  two  major  pieces  which  make  up  the  Layout 
Optimization  System.  There  is  a  library  of  callable  routines 
which  may  be  accessed  from  within  the  user's  application  program. 
There  is  also  an  interactive  program  which  the  user  can  make  use 
of  to  define  a  knowledge  base  of  archetypes  which  the  callable 
routines  can  use  in  creating  charts.  The  knowledge  base  consists 
of  3  files,  one  for  chart  archetypes, 

one  for  object  archetypes,  and  one  for  relation  archetypes.  These 
files  are  created  on  the  user's  current  directory. 
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8 . 2  Interactive  Chart  Definition 

The  interactive  chart  definition  program  is  used  to  create 
and  maintain  a  knowledge  base  of  information  which  then  can  be 
used  to  create  and  manipulate  charts-  This  program  is  accessed  by 
entering  "LAYOUT"  in  the  function  field  on  the  IISS  Function 
Screen.  Figure  8-4  is  the  first  screen  to  appear  when  the  program 
is  invoked: 


Figure  8-4 
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8-2.1  Chart  Functions 

When  starting  from  scratch,  the  first  thing  you  must  do  is 
define  your  chart.  To  start  this  process,  press  <PF5>.  The 
following  screen  will  appear: 


Figure  8-5 
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8. 2. 1.1  ADD  Chart 

To  create  a  new  chart,  press  <PF9>  to  ADD  a  chart.  The 
following  screen  will  appear: 


Figure  8-6 


Valid  entries  are: 

CHART  NAME  Up  to  10  alpha-numeric  characters 

CHART  ORIENTATION  Place  any  non-blank  character  next 
to  either  vertical  or  horizontal  to 
choose  the  orientation  for  your  chart. 
("Orientation"  means  the  general  way  in 
which  the  objects  will  be  positioned  on 
the  chart.  A  Vertical  orientation 
means  the  chart  will  start  at  a 
specified  point  and  progress  either  up 
or  down.  Horizontal  means  that  the 
chart  will  begin  at  a  specified  point 
and  progress  to  the  right.  If  left 
blank,  based  on  all  other  information 
the  user  enters,  the  software  will 
choose  the  Chart  Orientation  at  print 
time  in  order  to  optimize  readability. 
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LAYOUT  PREFERENCE  Place  any  non-blank  character  next 
to  your  choice  for  initial  layout 
preference.  If  you  choose  Left 
Downward,  the  chart  will  start  on  the 
left  and  progress  to  the  right  and 
down.  If  you  choose  Left  Upward,  the 
chart  will  start  on  the  left  and 
progress  to  the  right  and  up.  If  left 
blank,  based  on  all  other  information 
the  user  enters,  the  software  will 
choose  the  Layout  Preference  at  print 
time  in  order  to  optimize  readability. 

MINIMUM  SPACING  Enter  the  minimum  number  of  spaces 
you  wish  to  see  between  objects  on  your 
chart.  This  must  be  a  numeric  entry 
between  1  and  15.  This  field  is 
optional.  If  left  blank,  the  default 
is  1. 

Once  you  have  filled  in  the  screen  with  your 

choices,  press  <ENTER> .  The  following 
screen  will  appear: 


Layout  Opt  laisai ton  Systea 
Oiart  Funcdoo* 


1  Spec i ! lc  Itea  <PFS> 

I  All  <PF8> 

Add 

Upd'.te 

<PF9>  Delete 

<PF12> 

<PF16> 

Chart 

Nim  f  " 

□ 

| 

Chert  Orientation 

| 

1m  t  lal 

Layout  Preference 

)  [“"jVertical 

|  J jMomoMal 

f  1 Laf  t  Oovnvard 
l^jLeft  Upvard 

Klniaue  Spacing  Retveen  Objects  ;  | 

characters . 

i 


jWSG  '  •44*4  Brtar  data  to  add  another  or  uae  (XTTT _ applcatlonj 


Figure  8-7 


If  you  do  not  wish  to  create  another  chart,  press 
<QUIT>.  The  screen  illustrated  in  Figure  8-5  will 
return. 


8-9 


UM  620344200 
30  September  1990 


8. 2. 1.2  UPDATE  Chart 

If  you  wish  to  update  a  chart  definition,  while  on 
the  chart  function  main  screen  (Figure  8-5) ,  press 
<PF12>.  The  screen  shown  in  Figure  8-6  will  appear. 
Type  in  the  name  of  the  chart  you  wish  to  change  and 
the  new  data  selections.  (Any  field  left  blank  will 
default  to  its  previous  value.)  Press  <ENTER>.  If 
the  update  was  successful,  the  following  will  appear: 


Figure  8-8 


Press  <QUIT>  when  finished  updating. 
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8 . 2 . 1 . 3  DELETE  Chart 

To  delete  a  chart,  first  press  <PF16>  from  the  Chart 
Functions  Main  Screen  (Figure  8-5) .  The  following 
screen  will  appear: 


Figure  8-9 


Type  in  the  name  of  the  chart  you  wish  to  delete. 
Press  <ENTER> .  The  following  will  appear: 


Figure  8-10 


The  chart  and  all  of  its  related  objects  and 
relationships  will  be  deleted. 
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Press  <QUIT>  to  return  to  the  Chart  Functions  Main 
Screen . 
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8. 2. 1.4  RETRIEVE  Items 

The  last  two  options  available  under  Chart  Functions 
are  Retrieve  Specific  Item  and  Retrieve  All. 

If  you  press  <PF8>  to  retrieve  all  items,  a  list  of 
the  charts  you  have  defined  with  their  default  values 
will  appear. 


Layout  Optimization  System 

Chart  Pu&ctiooa 

htrtM 

Specific  Item 

<ffj>  Add 

<m> 

Delete  <FF16> 

Mirim 

All 

<m>  Update 

<FF12> 

Chart  Descriptions 

Char 

Hln 

Name 

Or  lent  Layout 

Space 

msr 

V  D 

1 

ITEST 

V  D 

1 

JMm. 

*  D 

7 

RODULClAftT  V  D 

1 

NTVauXT  V  D 

5 

i 

i 

ITEST 

B  0 

02 

i 

l 

j 

i*sc  'T' 

mpplcat loo 

Figure  8-11 


You  can  use  <TAB>  to  move  your  cursor  to  any  one  of 
the  items.  If  you  press  <ENTER>  with  the  cursor  on 
one  of  the  items,  that  item  will  become  the  default 
item.  That  means  that  any  of  the  future  choices  you 
make  will  refer  to  that  item  until  you  change  the 
default  item.  If  you  have  not  chosen  a  default  item, 
the  software  will  assume  that  the  choices  refer  to  the 
last  item  you  added  or  updated. 
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If  you  press  <PF5>  to  retrieve  a  specific  item,  the 
default  item  will  appear  on  the  screen  (either  the 
item  you  chose  as  default  or  the  last  item  you  added 
or  deleted) . 


Layout  Optimization  Systaa 

Chart  FwBctfoaj 

Specific  ltaa  <?F5>  Add  <?FV>  Delate  <?F16> 

Mttitvt  All  <FF8>  Update  <FF12> 


Chart  tom*.  (WTVCiUFT  ~] 

Chart  Orientation  Initial  layout  Preference 


B  Vertical 
Borizontal 


0Laft  Dovnward 
Left  Upvard 


Nlniaua  Spacing  Between  Objacta:  [  5]  character*. 


use  nn 


app  1  cat  loo 


Figure  8-12 


From  either  of  these  options,  press  <QUIT>  to  return 
to  the  Chart  Functions  main  screen. 

Press  <QUIT>  again  to  return  to  the  main  menu 
(Figure  8-4) . 
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8.2.2  Object  Functions 

Once  your  chart  is  defined,  you  need  to  define  the 
objects  contained  on  that  chart.  To  choose  the  object 
functions,  press  <PF6>  on  the  main  menu.  The 
following  screen  will  appear: 


Acirtive  Specific  I««* 
Fetr«»v«  All 


Layout  Optimization  System 
Ofcjoct  PuKitoo* 

<FFS>  Add  <FF9> 

<FF8>  Update  <FF12> 


1 

Del  it*  <FF16>  ^ 


Use 


applcat  ton ; 


Figure  8-13 
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8. 2. 2.1  ADD  Object 

If  no  objects  exist,  the  fir^  .  «_ning  you  must  do  is 
create  one  or  more.  Press  <PF9>  to  ADD  an  object. 

The  following  screen  will  appear: 


Ratratve  Specific  It*e 
t  f  * : v*  Ail 


Layoul  OpuattiltOD  Syi:»« 

fHACtiwu 

<FF5>  Add  <f F9> 

<m>  Upd«  i«  <FFi:> 


Otjact  Dalinnie 
For  Char t  •  f~ 


J 


0bj*c  t  Mao*  ^ 


Icon  Naoe  Q 


Connecter  Placement 


Or  If  mat  inf 
•  Any  Location 
I  Rot  too 
Top 

I  Rlfht 
j  Left 

j  tot  too  Rlfht  Corner 
|  Bottoa  Left  Corner 
j  Top  Right  Corner 
j  Top  Left  Comer 


Te re l na ( lng 
Any  Location 
tot  toe 
Top 
Rlfht 
Left 

tcttoe  Rlfht  Corner 
tot  toe  Left  Corner 
Top  Rifht  Corner 
Top  Left  Comer 


\  I  tee  added-  Inter  data  to  add  another  or  vac  < 


a  pp)  cat  ion 


Figure  8-14 


The  following  are  valid  entries: 


CHART 

OBJECT  NAME 

ICON  NAME 


Type  the  name  of  the  chart  the 
objects  belong  to 

Type  the  name  of  the  object 
being  defined 

Type  the  name  of  the  icon 
containing  the  object 


ORIGINATING  CONNECTOR 

PLACEMENT  Place  any  non-blank  character  in 

the  field  next  to  your  choice 
for  the  position  on  the  object 
from  which  the  connector  is  to 
originate  (ex.  "BOTTOM"  means 
that  you  want  the  connecter  to 
originate  from  the  bottom  of  the 
object  you  are  currently 
defining) . 
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TERMINATING 

CONNECTOR  PLACEMENT  Place  any  non-blank  character  in 

the  field  next  to  your  choice 
for  the  position  on  the  object 
to  which  the  object  you  are 
defining  is  connected  (ex. 

"TOP"  means  that  you  want  the 
connector  originating  from  the 
object  you  are  currently 
defining  to  terminate  into  the 
top  of  the  next  object) 

When  the  information  is  typed  in  as  you  want  it,  press 
<ENTER> .  The  following  will  appear: 


let! 1*' 
••tit** 


•  Specific  !in 

•  All 


Layout  Optimisation  System 
Otj*c(  Pv»ctlo«u 
<»F5>  Add  <m> 

<frt>  update  <?F12> 

Object  Definition 


For  Chart : ( 

— ! 

Object  Mao*  | 

Icon  Name  [ 

Coenec tor  Place*! 

ifit 

Originating 

Terminating 

i  Any  Location 

■ 

Any  Location 

lo:  !Ot 

lotto* 

Top 

Top 

light 

light 

1  Left 

Left 

lotto*  light  Corner 

lotto*  Right  Comer 

lotto*  Left  Corner 

lotto*  Left  Comer 

Top  light  Comer 

Top  light  Comer 

Top  Left  Corner 

— 

Top  Left  Comer 

Item  added  later  date  to  add  , 


applcat loo 


Figure  8-15 


If  you  wish  to  add  more  objects,  continue  entering  data. 
Press  <ENTER>  after  each  set  of  data.  To  return  to  the  Object 
Functions  main  screen  (Figure  8-13),  press  <QUIT>. 
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8. 2. 2. 2  UPDATE  Object 

To  update  an  already  existing  object,  press  <PF12>  from  the 
Object  Functions  main  screen  (Figure  8-13) .  The  screen  shown  in 
Figure  8-14  will  appear  containing  the  default  object  (if  no 
default  has  been  specified,  it  will  contain  the  last  object  you 
added  or  updated) .  Change  the  data  to  the  new  settings  (any 
field  not  changed  will  default  to  the  previous  entry;  if  there 
was  no  value  previously,  the  software  will  automatically  select 
settings  based  on  all  other  information  you  enter)  and  press 
<ENTER>.  The  following  will  appear: 
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Figure  8-16 

Press  <QUIT>  to  return  to  the  Object  Functions  main  screen 
(Figure  8-13) . 
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8.2.2. 3  DELETE  Object 


To  delete  an  object  you  have  created,  press  <PF16>  at  the 
Object  Functions  main  screen  (Figure  8-13) .  The  following  will 
appear: 


Figure  8-17 
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Enter  the  name  of  the  chart  and  the  name  of  the  object  to 
be  deleted  and  press  <ENTER>.  The  following  will  appear: 


Figure  8-18 

Press  <QUIT>  to  return  to  the  Object  Functions  main  screen 
(Figure  8-13) . 
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8. 2. 2. 4  RETRIEVE  Items 

The  last  two  options  available  under  Object  Functions  are 
Retrieve  Specific  Item  and  Retrieve  All. 

If  you  press  <PF8>  to  retrieve  all  items,  the  following 
screen  will  appear: 


Figure  8-19 
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Enter  the  name  of  the  chart  whose  objects  you  want  listed 
and  press  <ENTER>.  A  List  of  the  objects  you  have  defined  for 
that  chart  with  their  default  values  will  appear. 
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Figure  8-20 


You  can  use  <TAB>  to  move  your  cursor  to  any  one  of  the 
items.  If  you  press  <ENTER>  with  the  cursor  on  one  of  the 
items,  that  item  will  become  the  default  item.  That  means  that 
any  of  the  future  choices  you  make  will  refer  to  that  item  until 
you  change  the  default  item.  If  you  have  not  chosen  a  default 
item,  the  software  will  assume  that  the  choices  refer  to  the 
last  item  you  added  or  updated. 
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If  you  press  <PF5>  to  retrieve  a  specific  item,  the  default 
item  will  appear  on  the  screen  (either  the  item  you  chose  as 
default  or  the  last  item  you  added  or  deleted) . 
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Figure  8-21 


From  either 
Object  Functions 


of  these  options, 
main  screen. 


press  <QUIT>  to  return  to  the 
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8.2.3  Relation  Functions 

Now  that  the  chart  and  the  objects  have  been  defined,  you 
must  define  the  relationships  to  be  used  in  creating  the  chart. 
To  do  this  you  use  the  relation  functions.  At  the  Main  Menu 
(Figure  8-4)  press  <PF7>.  The  following  will  appear: 


Figure  8-22 
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8. 2. 3.1  ADD  Relation 

The  following  are  valid  entries  for  the  ADD  relation 
screen: 


CHART 

RELATION 


The  name  of  the  chart  to  which  the 
relation  applies. 


The  name  of  the  relation  being 
created . 


ORIGINATION 
ICON  NAME 


TERMINATION 
ICON  NAME 


COMPLEX 
ICON  NAME 


The  name  of  the  form  which 
contains  the  template  for  the 
origination  symbol  to  be  used  with 
this  relation  (if  any). 


The  name  of  the  form  which 
contains  the  template  for  the 
termination  symbol  to  be  used  with 
this  relation  (if  any). 


The  name  of  the  form  which 
contains  the  template  for  the 
complex  symbol  to  be  used  with 
this  relation  (if  any). 


ORIGINATING  CONNECTOR 

PLACEMENT  Place  any  non-blank  character  in 

the  field  next  to  the  location  on 
the  parent  object  from  which  you 
want  the  relation  to  start.  If  you 
do  not  choose,  the  Layout  System 
will  choose  for  you. 


TERMINATING  CONNECTOR 

PLACEMENT  Place  any  non-blank  character  in 

the  field  next  to  the  location  on 
the  child  object  into  which  you 
want  the  relation  to  terminate. 

If  you  do  not  choose,  the  Layout 
System  will  choose  for  you. 


SPECIAL  CHARACTERISTICS 

TWO  BEND  LINE  SLOPE  Place  any  non-blank  character  in 

the  field  next  to  the  direction  in 
which  you  want  any  sloped  lines  to 
progress.  If  you  do  not  choose, 
the  Layout  System  will  choose  for 
you . 
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SPECIAL  CHARACTERISTICS 

COMBINE  RELATIONS  Place  any  non-blank  character  in 

the  field  next  to  "yes"  or  "no" 
depending  upon  whether  you  want 
like  relations  combined  on  your 
chart . 

LINE  STYLE  Enter  the  keyword  for  the  type  of 

line  you  wish  to  use  to  represent 
the  relation  (SOLID,  DASH,  or 
DOT) ,  or  you  may  leave  blank.  If 
you  do  not  choose,  the  Layout 
System  will  choose  for  you. 

When  you  have  entered  your  choices,  press  <ENTER> .  The 
following  will  appear: 
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Figure  8-23 


If  you  wish  to  add  more  relations,  enter  the  data  and  press 
<ENTER> . 

When  you  have  finished  adding  relations,  press  <QUIT>  to 
return  to  the  Relation  Function  screen  (Figure  8-22) . 
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8. 2. 3. 2  UPDATE  Relation 

To  update  an  existing  relation,  press  <PF12>.  The  screen 
following  will  appear  with  either  the  relation  you  chose  as 
default  or  the  last  relation  you  added  or  updated  showing: 
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Figure  8-24 
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Make  whatever  changes  you  wish  to  the  data  and  press 
<ENTER>.  The  following  will  appear: 


Figure  8-25 


Press  <QUIT>  to  return  to  the  Relation  Functions  screen 
(Figure  8-22) . 
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8. 2. 3. 3  DELETE  Relation 

To  delete  an  existing  relation,  press  <PF16>  at  the  Relation 
Functions  screen.  The  following  will  appear: 


Figure  8-26 
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Enter  the  name  of  the  chart  to  which  the  relation  applies 
and  the  name  of  the  relation  you  wish  to  delete.  Press  <ENTER> . 
The  following  will  appear: 


Figure  8-27 


Press  <QUIT>  to  return  to  the  Relation  Functions  screen 
(Figure  8-22) . 
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8. 2. 3. 4  RETRIEVE  Items 

The  last  two  options  available  under  Relation  Functions  are 
Retrieve  Specific  Item  and  Retrieve  All. 

If  you  press  <PF8>  to  retrieve  all  items,  the  following 
screen  will  appear: 
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Figure  8-28 
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Enter  the  name  of  the  chart  whose  relations  you  want  listed 
and  press  <ENTER>.  A  list  of  the  relations  you  have  defined  for 
that  chart  with  their  default  values  will  appear. 
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You  can  use  <TAB>  to  move  your  cursor  to  any  one  of  the 
items.  If  you  press  <ENTER>  with  the  cursor  on  one  of  the  items, 
that  item  will  become  the  default  item.  That  means  that  any  of 
the  future  choices  you  make  will  refer  to  that  item  until  you 
change  the  default  item.  If  you  have  not  chosen  a  default  item, 
the  software  will  assume  that  the  choices  refer  to  the  last  item 
you  added  or  updated. 
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If  you  press  <PF5>  to  retrieve  a  specific  item,  the  default 
item  will  appear  on  the  screen  (either  the  item  you  chose  as 
default  or  the  last  item  you  added  or  deleted) . 


Figure  8-30 


From  either  of  these  options,  press  <QUIT>  to  return  to  the 
Relation  Functions  main  screen. 
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This  section  of  the  manual  describes  the  callable  routines 
used  by  the  Layout  Optimization  System.  They  are  listed 
alphabetically  with  a  brief  functional  description  in  Table  8.1 
below: 


TABLE  8 . 1  Callable  Layout  System  Routines 
ROUTINE  FUNCTION 


BEGCHT 

DCHART 

DELCHT 

DELOBJ 

DELREL 

DOBJTP 

DRELTP 

DRWCHT 

ENDCHT 

GINSNM 

INITFL 

MAKCHT 

MAKOBJ 

MAKREL 

PRNCHT 

TERMFL 


Change  the  application  program's  display  list  to  that 
of  the  chart  identified 
Describe  a  chart  archetype 

Delete  all  object  and  relation  definitions  for  a  named 
chart  instance 

Delete  an  object  instance  from  a  chart  instance 
Delete  a  relationship  instance  from  a  chart  instance 
Describe  an  object  archetype 
Describe  a  relation  archetype 

Layout  the  objects  and  relationships  for  a  chart 
Return  to  the  application  program's  original  display 
list 

Generate  an  instance  name 

Initialize  the  Layout  Optimization  System 
Create  an  instance  of  a  chart  archetype 
Create  an  instance  of  an  object  archetype 
Create  an  instance  of  a  relation  archetype 
Display  a  chart 

Terminate  the  Layout  Optimization  System 


The  use  of  each  routine  is  explained  in  detail  in  the 
following  sections.  This  includes  a  description  of  the  purpose 
of  the  routine,  the  format  for  calling  the  routine,  descriptions 
of  the  calling  parameters,  and  an  example  call.  Note  that  the 
calling  formats  and  example  are  given  in  COBOL  and  Str  and  Num  in 
the  parameter  format  mean  character  string  and  long  integer 
respectively.  Example  data  types  in  COBOL,  PL/I,  C,  and  Fortran 
are  described  in  Table  8.2: 

TABLE  8 . 2  Example  Data  Types 

COBOL  PL/ I  C  Fortran 

Num  S9 ( 5)  COMP  FIXED  BIN(31)  int  INTEGER 

Str  PIC  X (n)  CHAR ( N)  char[n]  CHARACTER*N 


NOTE:  A  C  character  string  may  contain  the  null  character  if  it 
is  after  the  last  character  the  FP  looks  at  (e.g.  after  the 
semicolon  in  a  qualified  path  name). 

NOTE:  PMSGLC  is  a  Form  Processor  callable  routine  which  appears 

in  most  of  the  examples  included  in  this  section.  The 
description  can  be  found  in  the  Form  Processor  User's  Manual. 
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oTE:  "OK*1  is  a  variable  name  defined  in  the  include  member 

PCODE . 
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BEGCH1 


8.3.1  BEGCHT 

This  routine  is  used  to  switch  the  application  program's 
display  list  to  that  of  the  specified  chart.  BEGCHT  is  required 
to  enable  the  application  program  to  have  access  to  the  forms 
used  to  pictorially  represent  the  objects  and  relationships  of 
the  chart.  Once  the  application  has  access  to  the  forms 
containing  the  archetypes,  it  can  place  the  correct  names,  etc. 
into  the  pictures  to  make  them  specific  to  each  instance. 

8 . 3 . 1 . 1  Calling  Format 

CALL  "BEGCHT"  USING  CHART-INSTANCE-NAME , 

RCODE . 

8. 3. 1.2  Parameter  Descriptions 


NAME  I/O  FORMAT  DEFINITION 

+ - + - H - + - + 


CHART- 

INSTANCE- 

NAME 

Input 

Str (10) 

■ 

The  name  of  the  chart. 

RCODE 

Output 

Str (5) 

The  routine  return  code.  The 
possible  values  are  defined  in 
the  include  member  FPCODE. 

+ - + - + - + - - - + 


8 . 3 . 1 . 3  Example 

WORKING-STORAGE  SECTION. 

COPY  FPCODE  OF  IISSCLIB. 

COPY  FPPARM  OF  IISSCLIB. 

01  CHART-INSTANCE-NAME  PIC  X ( 10 ) . 

PROCEDURE  DIVISION. 


CALL  "BEGCHT" 
IF  RCODE  =  OK 


USING  CHART-INSTANCE-NAME 
RCODE. 


ELSE 

CALL  " PMSGLC"  USING  RCODE. 
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DCHART 


8.3.2  DCHART 


This  routine  is  used  to  describe  a  new  chart  archetype,  or 
generic  prototype.  The  user  specifies  the  general  guidelines  he 
or  she  desires  the  Layout  System  to  use  when  designing  the  chart. 
These  preferences  are  specified  by  including  a  list  of  keywords. 
The  user  must  specify  the  length,  in  characters,  of  the  the 
keyword  list  (e.g.  if  the  user  specifies  the  list 
vertical , leftup,minspace=2  the  keyword  list  length  is  26). 

8. 3. 2.1  Calling  Format 

CALL  "DCHART"  USING  CHART-ARCHETY PE-REFERENCE-NAME , 

KEYWORD-LIST-LENGTH , 

KEYWORD-LIST, 

RCODE . 

8. 3. 2. 2  Parameter  Descriptions 

NAME  I/O  FORMAT  DESCRIPTION 

+ - + - + - + - + 


CHART- 

ARCHETYPE- 

REFERENCE- 

NAME 

Input 

Str (10) 

The  reference  name  for  the 
chart  archetype. 

KEYWORD- 

LIST-LENGTH 

Input 

Num 

Specifies  the  length  (in  char¬ 
acters)  of  the  keyword  list. 

KEYWORD- 

LIST 

Input 

Str 

A  list  of  chart  characteristic 
keywords  separated  by  commas. 
Refer  to  Section  8. 3.2. 3  below 
for  valid  keywords. 

RCODE 

Output 

U - - - 

Str (5) 

The  routine  return  code.  The 
possible  values  are  defined  in 
the  include  member  FPCODE. 
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DCHART 


8. 3. 2. 3  Valid  Keywords 


VERTICAL 

HORIZONTAL 

LEFTDOWN 

LEFTUP 

MINSPACE=99 


provide  vertical  object  orientation 
provide  horizontal  object  orientation 
provide  left  downward  initial  layout 
structure 

provide  left  upward  initial  layout 
structure 

minimum  spacing  between  objects 


3 . 3 . 2 . 4  Example 


WORKING-STORAGE  SECTION. 

COPY  FPCODE  OF  IISSCLIB. 

COPY  FPPARM  OF  IISSCLIB. 

01  CHART-ARCHETYPE-REFERENCE-NAME  PIC  X(10). 

01  KEYWORD-LIST-LENGTH  PIC  S9(05)  COMP  VALUE  30. 

01  KEYWORD-LIST  PIC  X(30). 

PROCEDURE  DIVISION. 


CALL  "DCHART"  USING  CHART-ARCHETYPE-REFERENCE-NAME, 

KEYWORD-LIST-LENGTH , 
KEYWORD-LIST, 

RCODE . 

IF  RCODE  =  OK 


ELS  E 

CALL  " PMSGLC"  USING  RCODE. 
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DELCHT 


8.3.3  DELCHT 


This  routine  deletes  all  object  and  relation  definitions  and 
frees  all  computer  resources  which  were  acquired  for  the  named 
chart  instance. 

8 . 3 . 3 . 1  Calling  Format 

CALL  "DELCHT"  USING  CHART-INSTANCE-NAME , 

RCODE . 


8. 3. 3. 2  Parameter  Descriptions 

NAME  I/O  FORMAT  DEFINITION 


CHART- 

INSTANCE- 

NAME 


Input 


Str(10) | The  name  of  the  chart  for  which 
the  object  and  relation  defin¬ 
itions  will  be  deleted. 


RCODE 


i 

+  - 


Output 


St r ( 5 ) 


The  routine  return  code.  The 
possible  values  are  defined  in 
the  include  member  FPCODE. 


l 

■  + 


8 . 3 . 3 . 3  Example 

WORKING-STORAGE  SECTION. 

COPY  FPCODE  OF  IISSCLIB. 

COPY  FPPARM  OF  IISSCLIB. 

01  CHART-INSTANCE-NAME  PIC  X ( 10) . 

PROCEDURE  DIVISION. 


CALL  "DELCHT"  USING 
IF  RCODE  =  OK 


CHART-INSTANCE-NAME , 
RCODE. 


ELSE 

CALL  "PMSGLC"  USING  RCODE. 
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DELOBJ 


8.3.4  DELOBJ 


This  routine  deletes  the  named  object  instance  from  a  chart 
instance . 

8. 3. 4.1  Calling  Format 

CALL  "DELOBJ"  USING  CHART- INSTANCE-NAME , 

OBJECT-INSTANCE-NAME , 

RCODE . 

8. 3. 4. 2  Parameter  Descriptions 


NAME  I/O  FORMAT  DESCRIPTION 

CHART- 

INSTANCE- 

NAME 

Input 

Str (10) 

The  instance  name  of  the  chart 
containing  the  object  to  be 
deleted . 

OBJECT- 

INSTANCE- 

NAME 

Input 

Str (10) 

The  instance  name  of  the  object 
to  be  deleted. 

RCODE 

|  Output 

1  Str ( 5 ) 

|  The  routine  return  code.  The 

possible  values  are  defined  in 
the  include  member  FPCODE. 


+ - + - h - + - + 
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8. 3. 4. 3  Example 

WORKING-STORAGE  SECTION. 

COPY  FPCODE  OF  IISSCLIB. 

COPY  FPPARM  OF  IISSCLIB. 

01  CHART-INSTANCE-NAME  PIC  X(10). 

01  OBJECT-INSTANCE-NAME  PIC  X(10). 
PROCEDURE  DIVISION. 


CALL  "DELOBJ"  USING  CHART-INSTANCE-NAME, 

OBJECT-INSTANCE-NAME , 
RCODE . 

IF  RCODE  =  OK 


ELSE 

CALL  "PMSGLC"  USING  RCODE. 


•4  1 


DELOBJ 
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8.3.5  DELREL 

This  routine  is  used  to  delete  a  relationship  instance  from  a 
chart . 

8. 3. 5.1  Calling  Format 

CALL  "DELREL"  USING  CHART-INSTANCE-NAME, 

RELATIONSHIP- INSTANCE-NAME, 
PARENT-OBJECT-INSTANCE-NAME , 

CHILD-OBJECT- INSTANCE-NAME, 

RCODE . 

8. 3. 5. 2  Parameter  Descriptions 


NAME  I/O  FORMAT  DESCRIPTION 


- -1 

CHART- 

INSTANCE- 

NAME 

- -i 

Input 

- i 

Str ( 10) 

The  instance  name  of  the  chart 
containing  the  relationship  to 
be  deleted 

RELATION- 

SHIP- 

INSTANCE- 

NAME 

Input 

Str ( 10) 

The  instance  name  of  the 
relationship  to  be  deleted 

PARENT- 

OBJECT- 

INSTANCE- 

NAME 

Input 

Str (10) 

The  instance  name  of  the  parent  | 

or  origination  object  of  the 
relationship 

CHILD- 

OBJECT- 

INSTANCE- 

NAME 

Input 

Str ( 10 ) 

The  instance  name  of  the  child 
or  termination  object  of  the 
relationship 

RCODE 

T  "1 

1  o 

1  c 

1  ft 

i  n 

1  c 

l  r+ 

Str (5) 

t- - 

The  routine  return  code.  The 
possible  values  are  defined  in  j 

the  include  member  FPCODE.  j 

t - -t- 
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8 . 3 . 5 . 3  Example 

WORKING-STORAGE  SECTION. 

COPY  FPCODE  OF  IISSCLIB. 

COPY  FPPARM  OF  IISSCLIB. 

01  CHART-INSTANCE-NAME 
01  RELATIONSHIP-INSTANCE-NAME 
01  PARENT-OBJECT-INSTANCE-NAME 
01  CHILD-OBJECT-INSTANCE-NAME 
PROCEDURE  DIVISION. 


PIC  X(lCj . 
PIC  X(10)  . 
PIC  X(10)  . 
PIC  X ( 10)  . 


CALL  "DELREL"  USING  CHART-INSTANCE-NAME, 

RELATIONSHIP-INSTANCE-NAME , 
PARENT-OBJECT-INSTANCE-NAME , 
CHILD-OBJECT-INSTANCE-NAME, 
RCODE . 

IF  RCODE  =  OK 


ELSE 

CALL  " PMSGLC"  USING  RCODE. 
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8.3.6  DOBJTP 

This  routine  is  used  to  describe  an  object  archetype.  You 
must  specify  the  name  of  the  chart  archetype  which  will  use  the 
object  archetype  being  created,  the  name  of  the  object  archetype 
being  created,  the  name  of  the  form  where  the  object  archetype  if: 
defined,  a  keyword  list  containing  keywords  to  specify  connection;; 
should  originate  and  terminate,  and  the  length  (in  characters)  ot 
the  keyword  list.  For  example,  if  the  keyword  list 
org_bottom , trm_top  is  used,  the  keyword  list  length  is  13.  The 
keyword  list  is  optional.  If  none  is  specified,  the  Layout  System 
will  choose  the  positioning  of  connectors. 

8. 3. 6.1  Calling  Format 

CALL  "DOBJTP"  USING  CHART-ARCHETYPE-REFERENCE-NAME, 

OBJECT-ARCHETYPE-REFERENCE-NAME, 
OBJECT-FORM-NAME , 

KEYWORD-LIST-LENGTH , 

KEYWORD-LIST, 

RCODE . 
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8. 3.6.2  Parameter  Descriptions 


NAME  I/O  FORMAT  DESCRIPTION 

CHART- 

ARCHETYPE- 

REFERENCE- 

NAME 

Input 

Str (10) 

The  name  of  the  chart  archetype 
to  which  the  description  being 
defined  is  to  be  assigned. 

OBJECT- 

ARCHETYPE- 

REFERENCE- 

NAME 

Input 

Str ( 10) 

The  name  of  the  object  archetype 
to  be  defined. 

OBJECT- 

FORM-NAME 

Input 

Str (10) 

The  name  of  the  form  tc  be  used 
as  the  pictorial  representation 
of  this  object. 

KEYWORD- 

LIST- 

LENGTH 

Input 

Num 

The  length  of  the  keyword  list. 

KEYWORD- 

LIST 

Input 

Str 

A  list  of  object  characteristic 
keywords  separated  by  commas. 
Refer  to  Section  8. 3. 6. 3  below 
for  valid  keywords. 

RCODE 

1  Output 

I  Str ( 5 ) 

(The  routine  return  code.  The 

possible  values  are  defined  in 
the  include  member  FPCODE. 


+ - H - h - + 


8 . 3 . 6 . 3  Valid  Keywords 


0RG_B0TT0M 

-  all 
the 

originating  connections  shou’d 
bottom  of  the  object. 

be 

located  at 

ORG  TOP 

-  all 
the 

originating  connections  should 
top  of  the  object. 

be 

located  at 

ORG_LEFT 

-  all 
the 

originating  connections  should 
left  of  the  object. 

be 

located  to 

0RG_RIGHT 

-  all 
the 

originating  connections  should 
right  of  the  object. 

be 

located  to 

TRM  ^BOTTOM 

-  all 
the 

terminating  connections  should 
bottom  of  the  object. 

be 

1  oca tod  at 

TRMTOP 

-  all 
the 

terminating  connections  should 
top  of  the  object. 

be 

located  at 
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TRM_ 

LEFT 

-  all 

the 

TRM_ 

RIGHT 

-  all 

the 

ORG_ 

LOWR 

-  all 

the 

ORG_ 

LOW_L 

-  all 

the 

ORG_ 

UP_L 

-  all 

the 

ORG_ 

UP-R 

-  all 

the 

TRM_ 

LOWR 

-  all 

the 

TRM_ 

LOW_L 

-  all 

the 

TRM_ 

UP_R 

-  all 

the 

TRM_ 

UP_L 

-  all 

the 

terminating  connections  should  be  located 
left  of  the  object. 

terminating  connections  should  be  located 
right  of  the  object. 

originating  connections  should  be  located 
bottom  right-hand  corner  of  the  object, 
originating  connections  should  be  located 
bottom  left-hand  corner  of  the  object, 
originating  connections  should  be  located 
upper  left-hand  corner  of  the  object, 
originating  connections  should  be  located 
upper  right-hand  corner  of  the  object, 
terminating  connections  should  be  located 
bottom  right-hand  corner  of  the  object, 
terminating  connections  should  be  located 
bottom  left-hand  corner  of  the  object, 
terminating  connections  should  be  located 
upper  right-hand  corner  of  the  object, 
terminating  connections  should  be  located 
upper  left-hand  corner  of  the  object. 


t  G 
to 
on 

on 

on 

on 

on 

on 

on 

on 


8 . 3 . 6 . 4  Example 


WORKING-STORAGE  SECTION. 

COPY  FPCODE  OF  IISSCLIB. 

COPY  FPPARM  OF  IISSCLIB. 

01  CHART-ARCHETYPE-REFERENCE-NAME 
0 1  OBJECT-ARCHETYPE-REFERENCE-NAME 
01  OBJECT-FORM-NAME 
01  KEYWORD-LIST-LENGTH 
01  KEYWORD-LIST 
PROCEDURE  DIVISION. 


pic  x c io )  . 

PIC  X ( 10)  . 

PIC  X ( 10)  . 

PIC  S9 ( 5 )  COMP  VALUE  30. 
PIC  X ( 30)  . 


CALL  "DOBJTP"  USING  CHART-ARCHETYPE-REFERENCE-NAME , 

OBJECT- ARCHETYPE -REFERENCE-NAME, 
OBJECT-FORM-NAME , 
KEYWORD-LIST-LENGTH , 

KEYWORD-LIST, 

RCODE . 

IF  RCODE  =  OK 


ELSE 

CALL  " PMSGLC"  USING  RCODE. 
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8.3.7  DRELTP 


This  routine  is  used  to  describe  a  relation  archetype.  You 
must  specify  the  name  of  the  chart  archetype  to  which  the  relation 
applies,  the  name  of  the  relation  being  created,  the  name  of  the 
forms  containing  the  definitions  of  the  termination  and 
origination  symbols,  the  name  of  the  form  containing  the  complex 
symbol  used  (complex  symbol  is  any  symbol  which  connects  one 
parent  object  to  two  or  more  child  objects),  the  style  of  the  line 
used  to  represent  the  relation,  a  list  of  keywords  to  describe  the 
relationship,  and  the  length  of  the  keyword  list  in  characters. 

For  example,  if  the  keyword  list  org_right , trm_left , slopedown  is 
used  the  keyword  list  length  is  28. 

8. 3.7.1  Calling  Format 

CALL  "DRELTP"  USING  CHART-ARCHETYPE-REFERENCE-NAME , 

RELATION-ARCHETYPE-REFERENCE-NAME, 
TERMINATION-SYMBOL-FORM-NAME , 

ORIGINATION -SYMBOL- FORM-NAME , 
COMPLEX-SYMBOL-FORM-NAME , 

LINE-STYLE, 

KEYWORD-LIST-LENGTH , 

KEYWORD-LIST, 

RCODE . 
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8. 3. 7. 2  Parameter  Descriptions 


NAME  I/O  FORMAT  DESCRIPTION 

CHART- 

ARCHETYPE- 

REFERENCE- 

NAME 

Input 

Str (10) 

The  name  of  the  chart  archetype 
to  which  the  description  being 
defined  is  to  be  assigned. 

RELATION- 

ARCHETYPE- 

REFERENCE- 

NAME 

Input 

Str(10) 

The  name  of  the  relationship 
archetype  to  be  defined. 

TERMINATION- 

SYMBOL-FORM- 

NAME 

Input 

Str ( 10 ) 

The  name  of  the  form  to  be  used 
as  the  pictorial  representation 
of  the  termination  symbol  of 
this  relation . 

ORIGINATION- 
SYMBOL-  FORM- 
NAME 

Input 

Str ( 10) 

The  name  of  the  form  to  be  used 
as  the  pictorial  representation 
of  the  origination  symbol  of 
this  relation. 

COMPLEX- 

SYMBOL-FORM- 

NAME 

Input 

i 

Str ( 10) 

The  name  of  the  form  to  be  used 
as  the  pictorial  representation 
of  a  complex  relation. 

LINE-STYLE 

Input 

Str ( 10) 

The  stretchy  line  style  defin¬ 
ition  for  the  connector  line 
expressed  as  a  keyword.  Refer 
to  Section  8. 3. 7. 3  below  for 
valid  keywords. 

KEYWORD- 

LIST-LENGTH 

Input 

Num 

Specifies  the  length  (in  char¬ 
acters)  of  the  keyword  list. 

KEYWORD-LIST 

Input 

Str 

A  list  of  relation  character¬ 
istic  keywords  separated  by 
commas.  Refer  to  Section 

8. 3. 7. 4  for  valid  keywords. 

RCODE 

Output 

Str ( 5 ) 

The  routine  return  code.  The 
possible  values  are  defined  in 
the  include  member  FPCODE. 

H - — - f"  — - 1 - 1 - h 
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8. 3. 7. 3  Valid  Keywords  for  Line-Style 


SOLID  -  the  line  is  to  be  represented  by  a  solid  line. 

DASH  -  the  line  is  to  be  represented  by  a  dashed  line. 

DOT  -  the  line  is  to  be  represented  by  a  dotted  line. 

DEFAULT  -  the  Form  Processor  will  determine  the  style  of  the 

line. 


8. 3. 7. 4  Valid  Keywords  for  Keyword-List 


ORG_RIGHT  -  the  relationship  originates  from  the  right-hand 
side  of  an  object. 

ORG_LEFT  -  the  relationship  originates  from  the  left-hand 
side  of  an  object. 

ORG_BOTTOM  -  the  relationship  originates  from  the  bottom  of 
an  object. 

ORG_TOP  -  the  relationship  originates  from  the  top  of  an 
ob j  ect . 

TRM_RIGHT  -  the  relationship  terminates  on  the  right-hand 
side  of  an  object. 

TRM_LEFT  -  the  relationship  terminates  on  the  left-hand 
side  of  an  object. 

TRM_B0TT0M  -  the  relationship  terminates  on  the  bottom  of  an 
object. 

TRM_TOP  -  the  relationship  terminates  on  the  top  of  an 
object. 

SLOPEUP  -  the  relationship  has  two  bends  and  slopes 
upward . 

SLOPEDOWN  -  the  relationship  has  two  bends  and  slopes 
downward. 

SLOPELEFT  -  the  relationship  has  two  bends  and  slopes  to  the 
lef  t . 

SLOPERIGHT  -  the  relationship  has  two  bends  and  slopes  to  the 
right . 

COMBINE  -  pictorially  combine  relationships  of  this  type, 
whenever  possible,  when  the  chart  is  drawn. 
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8. 3.7.5  Example 


WORKING-STORAGE  SECTION. 
COPY  FPCODE  OF  IISSCLIB. 
COPY  FPPARM  OF  IISSCLIB. 


01 

CHART-ARCHETYPE-REFERENCE-NAME 

PIC 

X(10) 

01 

RELATION-ARCHETYPE-REFERENCE-NAME 

PIC 

X(10) 

01 

TERMINATION-SYMBOL-FORM-NAME 

PIC 

X(10) 

01 

ORIGINATION-SYMBOL-FORM-NAME 

PIC 

X  ( 1 0 ) 

01 

COMPLEX-SYMBOL-FORM-NAME 

PIC 

X(10) 

01 

LINE-STYLE 

PIC 

x  ( 10) 

01 

KEYWORD- LI ST- LENGTH 

PIC 

S9  ( 5 ) 

01 

KEYWORD-LIST 

PIC 

X  (  30) 

PROCEDURE  DIVISION. 


COMP 

VALUE  30. 


CALL  "DRELTP"  USING  CHART -ARCHETYPE -REFERENCE --NAME  , 

RELATION-ARCHETYPE-REFERENCE-NAME, 
TERMINATION-SYMBOL-FORM-NAME , 
ORIGINATION-SYMBOL-FORM-NAME , 
COMPLEX-SYMBOL- FORM-NAME , 
LINE-STYLE, 

KEYWORD-LIST-LENGTH , 

KEYWORD-LIST, 

RCODE . 

IF  RCODE  =  OK 


ELSE 

CALL  " PMSGLC"  USING  RCODE. 
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8.3.8  DRWCHT 

This  routine  is  used  to  layout  the  objects  and  relationships 
for  a  chart. 

8. 3.8.1  Calling  Format 

CALL  "DRWCHT"  USING  CHART-INSTANCE-NAME , 

RCODE . 


3.8.2  Parameter 

Descript ions 

NAME 

I/O 

FORMAT 

DESCRIPTION 

CHART- 

INSTANCE- 

NAME 

Input 

Str(10) 

The  instance  name  of  the  chart. 

RCODE 

Output 

h  — - —  —  H 

Str (5) 

The  routine  return  code.  The 
possible  values  are  defined  in 
the  include  member  FPCODE. 

8 . 3 . 8 . 3  Example 

WORKING-STORAGE  SECTION. 

COPY  FPCODE  OF  IISSCLIB. 

COPY  FPPARM  OF  IISSCLIB. 

01  CHART-INSTANCE-NAME  PIC  X ( 10 )  - 

PROCEDURE  DIVISION. 


CALL  "DRWCHT"  USING 
IF  RCODE  =  OK 


CHART-INSTANCE-NAME , 
RCODE. 


ELSE 

CALL  " PMSGLC"  USING  RCODE. 
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8.3.9  ENDCHT 


This  routine  returns  the  application  program's  display  list 
from  the  chart  specified  in  the  BEGCHT  routine  to  the  application 
program's  original  display  list. 

8 . 3 . 9 . 1  Calling  Format 

CALL  "ENDCHT"  USING  RCODE . 


8 . 3 . 9 . 2  Parameter  Descriptions 

NAME  I/O  Format  Definition 


Output | St r ( 5 )  [The  routine  return  code.  The 

possible  values  are  defined  in  the 


j include  member  FPCODE. 


8 . 3 . 9 . 3  Example 

WORKING-STORAGE  SECTION. 
COPY  FPCODE  OF  IISSCLIB. 
COPY  FPPARM  OF  IISSCLIB. 
PROCEDURE  DIVISION. 


CALL  "ENDCHT"  USING  RCODE. 
IF  RCODE  =  OK 


ELSE 

CALL 


" PMSGLC"  USING  RCODE. 
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8.3.10  GINSNM 

This  routine  is  used  to  generate  an  instance  name.  It  is 
provided  to  give  the  application  program  a  means  to  create  a 
unique  instance  name  which  can  be  used  in  the  MAKCHT,  MAKOBJ  or 
MAKREL  routine  calls.  Use  of  this  routine  is  not  required. 

8.3.10.1  Calling  Format 

CALL  "GINSNM"  USING  INSTANCE-NAME, 

RCODE . 

8.3.10.2  Parameter  Descriptions 

NAME  I/O  Format  Definition 


4- - 1 

INSTANCE- 

NAME 

V - H 

Output 

Str ( 10) 

The  generated  instance  name.  This' 
name  will  be  nine  characters  long  j 
|and  it  will  be  unique. 

RCODE 

+ - 

Output 

h - H 

Str ( 5 ) 

| 

h - - 

The  routine  return  code.  The 
possible  values  are  defined  in  the 
include  member  FPCODE. 

8.3.10.3  Example 

WORKING-STORAGE  SECTION. 

COPY  FPCODE  OF  IISSCLIB. 

COPY  FPPARM  OF  IISSCLIB. 

01  INSTANCE-NAME  PIC  X(10). 

PROCEDURE  DIVISION. 


CALL  "GINSNM" 
IF  RCODE  =  OK 


USING  INSTANCE-NAME, 
RCODE. 


ELSE 

CALL  "PMSGLC"  USING  RCODE. 
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8.3.11  INITFL 


This  routine  is  used  to  acquire  and  initialize  the  computer 
resources  that  will  be  required  by  the  application  proqram. 

8.3.11.1  Calling  Format 

CALL  "INITFL"  USING  RCODE . 

8.3.11.2  Parameter  Description' 

NAME  I/O  Format  Definition 


-+- 


RCODE 


Output 


Str(5)  I  The  routine  return  code.  The 
[possible  values  are  defined  in 
! the  include  member  PFCODE. 


8.3.11.3  Example 

WORKING-STORAGE  SECTION. 
COPY  FPCODE  OF  IISSCLIB. 
COPY  FPPARM  OF  IISSCLIB. 
PROCEDURE  DIVISION. 


CALL  "INITFL"  USING  RCODE. 
IF  RCODE  =  OK 


ELSE 

CALL  "PMSGLC"  USING  RCODE. 
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8.3.12  MAKCHT 

This  routine  is  used  to  create  an  instance  of  a  chart  from 
the  chart  archetype  reference  name  specified.  The  archetype  can 
be  one  created  at  run-time,  or  it  can  be  one  which  was  previously 
created  and  resides  in  a  knowledge  base. 

8.3.12.1  Calling  Format 

CALL  "MAKCHT"  USING  CHART-INSTANCE-NAME, 

CHART-ARCHETYPE-REFERENCE-NAME, 

RCODE . 

8.3.12.2  Parameter  Descriptions 

NAME  I/O  Format  Definition 


- H 

CHART- 

INSTANCE- 

NAME 

b - 

Input 

i - -i 

Str ( 10) 

The  instance  name  of  the  chart  to! 
be  created. 

I 

CHART- 

ARCHETYPE- 

REFERENCE- 

NAME 

Input 

Str(10) 

The  reference  name  of  the  chart 
archetype  to  use  to  create  the 
chart.  { 

RCODE 

Output 

1 - - 

Str (5) 

i - j 

The  routine  return  code.  The  j 
possible  values  are  defined  in  i 
the  include  member  FPCODE. 

UM  620344 
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WORKING-STORAGE  SECTION. 

COPY  FPCODE  OF  IISSCLIB. 

COPY  FPPARM  OF  IISSCLIB. 

01  CHART-INSTANCE-NAME 
01  CHART-ARCHETYPE-REFERENCE-NAME 
PROCEDURE  DIVISION. 


CALL  "MAKCHT"  USING  CHART- I NSTANCE-NAME , 

CHART-ARCHETYPE-INSTANCE-NAME , 
RCODE . 

IF  RCODE  =  OK 


ELSE 

CALL  " PMSGLC"  USING  RCODE. 


PIC  X ( 10)  . 
PIC  X ( 10)  . 
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8.3.13  MAKOBJ 

This  routine  is  used  to  create  an  instance  of  the  object 
archetype  using  the  object  archetype  specified.  The  object 
archetype  can  be  created  at  run-time  or  it  can  be  on  which  was 
previously  created  and  which  exists  in  the  knowledge  base. 

8.3.13.1  Calling  Format 

CALL  "MAKOBJ"  USING  CHART- INSTANCE-NAME , 

OBJECT-INSTANCE-NAME, 

OBJECT- ARCHETYPE-REFERENCE-NAME, 

RCODE . 

8.3.13.2  Parameter  Descriptions 

NAME  I/O  Format  Definition 


- H 

CHART- 

INSTANCE- 

NAME 

h - - 

Input 

i - 

Str (10) 

The  instance  name  of  the  chart  to| 
which  the  object  being  created  is 
to  be  assigned. 

OBJECT- 

INSTANCE- 

NAME 

Input 

Str ( 10) 

The  instance  name  of  the  object  ! 
which  is  being  created.  j 

OBJECT- 

ARCHETYPE- 

REFERENCE- 

NAME 

Input 

Str ( 10 ) 

The  reference  name  of  the  object  ■ 
archetype  to  use  to  create  the 
object. 

1 

! 

RCODE 

Output 

Str (5) 

The  routine  return  code.  The  : 

possible  values  are  defined  in 
the  include  member  FPCODE. 
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WORKING-STORAGE  SECTION. 

COPY  FPCODE  OF  IISSCLIB. 

COPY  FPPARM  OF  IISSCLIB. 

01  CHART-INSTANCE-NAME 
01  OBJECT-INSTANCE-NAME 
01  OBJECT-ARCHETYPE-REFERENCE-NAME 
PROCEDURE  DIVISION. 


CALL  "MAKOBJ"  USING  CHART-INSTANCE-NAME , 

OBJECT-INSTANCE-NAME , 

OBJ ECT-ARCHETY PE -INSTANCE -NAME , 
RCODE . 

IF  RCODE  =  OK 


ELSE 

CALL  "PMSGLC"  USING  RCODE. 


PIC  X(10) . 
PIC  X ( 10)  . 
PIC  X(10)  . 
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8.3.14  MAKREL 

This  routine  is  used  to  create  an  instance  of  a  relation 
archetype  using  the  relation  archetype  specified.  The  relation 
archetype  can  be  created  at  run-time  or  it  can  be  one  which  was 
created  previously  and  exists  in  the  knowledge  base. 

8.3.14.1  Calling  Format 

CALL  "MAKREL"  USING  CHART-INSTANCE-NAME, 

RELATIONSHIP-INSTANCE-NAME , 
PARENT-OBJECT- INSTANCE-NAME , 
CHILD-OBJECT-INSTANCE-NAME , 

RELATION -ARCHETYPE -RE TERENCE -NAME , 
LABEL-LENGTH, 

LABEL, 

RCODE . 
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8.3.14.2  Parameter  Descriptions 


NAME  I/O  Format  Definition 


- H 

CHART- 

INSTANCE- 

NAME 

- -l 

Input 

- 1 

Str (10) 

The  instance  name  of  the  chart  to 
which  this  relationship  is  to  be 
assigned . 

RELATION- 

SHIP- 

INSTANCE- 

NAME 

Input 

Str ( 10) 

The  instance  name  of  the  relation 
being  created.  This  name  has  a 
has  a  maximum  of  9  characters; 
the  last  character  must  be  blank. 
This  is  so  that  origination, 
termination,  and  complex  form 
instances  can  be  referenced  in 
the  application  program  by  adding 
"0",  "T",  or  "C"  to  the  end  of 
the  relationship  instance  name. 

PARENT- 

OBJECT- 

INSTANCE- 

NAME 

Input 

Str ( 10) 

The  instance  name  of  the  parent 
(origination)  object. 

CHILD- 

OBJECT- 

INSTANCE- 

NAME 

Input 

Str ( 10) 

The  instance  name  of  the  child 
(termination)  object. 

RELATION- 

ARCHETYPE- 

REFERENCE- 

NAME 

Input 

Str (10) 

The  reference  name  of  the  rela¬ 
tion  archetype  from  which  to 
create  the  relationship. 

LABEL- 

LENGTH 

Input 

Num  | The  length  of  the  text  string  in 

] in  the  label  parameter. 

LABEL 

Input 

Str 

A  non-mod i f iable  text  string  to 
be  associated  with  the  relation. 

RCODE 

Output 

t- - 

Str (5) 

h - 

The  routine  return  code.  The 
possible  values  are  defined  in 
the  include  member  FPCODE. 

i- - 
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8.3.14.3 

Example 

WORKING-STORAGE  SECTION. 

COPY 

FPCODE  OF  IISSCLIB. 

COPY 

FPPARM  OF  IISSCLIB. 

01 

CHART-INSTANCE-NAME 

PIC 

x ( 10) . 

01  RELATIONSHIP-INSTANCE-NAME 

PIC 

X ( 10)  . 

01 

PARENT-OBJECT- INSTANCE-NAME 

PIC 

X ( 10 )  . 

01 

CHILD-OBJECT- INSTANCE-NAME 

PIC 

x  ( 1 0  )  . 

01 

RELATICN-ARCHETYPE-REFERENCE-NAME 

PIC 

x ( 10 )  . 

01 

LABEL-LENGTH 

PIC 

S9 ( 05 )  COMP 

01 

LABEL 

PIC 

X(??) . 

PROCEDURE  DIVISION. 


CALL  "MAKREL"  USING  CHART- INSTANCE-NAME , 

RELATIONSHIP-INSTANCE-NAME, 
PARENT-OBJECT-INSTANCE-NAME , 
CHILD-OBJECT-INSTANCE-NAME , 
RELATION-ARCHETYPE-REFERENCE-NAME, 
LABEL-LENGTH, 

LABEL, 

RCODE . 

IF  RCODE  =  OK 


ELSE 

CALL  " PMSGLC"  USING  RCODE. 
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8.3.15  PRNCHT 

This  routine  is  used  to  display  a  chart  on  the  device 
specified . 

8.3.15.1  Calling  Format 

CALL  "PRNCHT"  USING  CHART-INSTANCE-NAME, 

DISPLAY-DEVICE-TYPE, 
DISPLAY-DEVICE-NAME, 
PAGINATION-STYLE , 

RCODE . 


8.3.15.2  Parameter  Descriptions 


NAME  I/O  Format  Definition 

+ - + - + - + - + 


CHART- 

INSTANCE- 

NAME 


Input 


Str (10) 


The  instance  name  of  the  chart 
to  be  displayed. 


- 1 

DISPLAY- 

DEVICE¬ 

TYPE 

h - 

Input 

i- - H 

Str (10) 

The  type  of  device  to  be  used 
for  the  display  (e.g.  LN03). 

DISPLAY- 

DEVICE¬ 

NAME 

Input 

Str ( 10 ) 

1 

The  name  of  the  device  to  be 
used  for  the  display. 

1 

PAGINATION- 

STYLE 

Input 

Str ( 10 ) 

A  keyword  used  to  specify  the 
pagination  style  (see  section 
8.3.15.3  for  a  list  of  valid 
keywords) . 

RCODE 

Output 

L - 

Str (5) 

t- - - 

The  routine  return  code.  The 
possible  values  are  defined  in 
the  include  member  PFCODE. 

L - _L 
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8.3.15.3  Pagination  Style  Keywords 

LOGICAL  -  Provide  logical  pagination. 

PHYSICAL  -  Provide  physical  pagination. 

BROWSE  -  Allow  the  user  a  "read-only"  means  of  examining 

forms.  The  user  may  enter  window  manager  mode  and 
scroll  the  form  around.  Application  function  keys 
are  not  enabled  and  data  is  not  enterable. 

8.3.15.4  Example 

WORKING-STORAGE  SECTION. 

COPY  FPCODE  OF  IISSCLIB. 

COPY  FPPARM  OF  IISSCLIB. 

01  CHART-INSTANCE-NAME 
01  DISPLAY-DEVICE-TYPE 
01  DISPLAY-DEVICE-NAME 
01  PAGINATION-STYLE 
PROCEDURE  DIVISION. 


PIC  X  ( 10)  . 
PIC  X (10)  . 
PIC  X(10)  . 
PIC  X(10)  . 


CALL  "PRNCHT"  USING  CHART-INSTANCE-NAME, 

DISPLAY-DEVICE-TYPE , 
DISPLAY-DEVICE-NAME , 
PAGINATION-STYLE , 
RCODE . 

IF  RCODE  =  OK 


ELSE 

CALL  "PMSGLC"  USING  RCODE. 
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8.3.16  TERMFL 

This  routine  is  used  to  relinquish  the  computer  resources 
acquired  during  the  use  of  the  system. 

8.3.16.1  Calling  Format 

CALL  "TERMFL"  USING  RCODE . 


8.3.16.2  Parameter  Descriptions 

NAME  I/C  Format  Definition 


RCODE 


Output 


Str (5) 


The  routine  return  code.  The 
possible  values  are  defined  in 
the  include  member  PFCODE. 


8.3.16.3  Example 

WORKING-STORAGE  SECTION. 
COPY  FPCODE  OF  II3SCLIB. 
COPY  FPPARM  OF  IISSCLIB. 
PROCEDURE  DIVISION. 


CALL  "TERMFL"  USING  RCODE. 
IF  RCODE  =  OK 


ELSE 

CALL  " PMSGLC"  USING  RCODE. 
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SECTION  9 

THREE  DIMENSIONAL  (3-D)  GRAPHICS 


UI-PLUS  has  the  capability  of  providing  three  dimensional 
(3-D)  wire-frame  graphics.  This  ability  has  been  implemented  in 
accordance  with  the  PHIGS  (Programmer's  Hierarchical  Interactive 
Graphics  System)  standard,  ANSI  X3. 144-198. 

The  basic  philosophy  of  PHIGS  is  that  a  graphic  picture  is 
created  by  grouping  together  commands  which  create  different  parts 
of  the  picture.  For  example,  an  arrow  may  oe  drawn  by  grouping 
together  the  commands  to  draw  2  polylines.  These  groups  of 
commands  are  called  structures.  A  more  complex  picture  may  be 
drawn  by  grouping  together  commands  to  draw  parts  of  the  picture 
and  commands  which  pull  other  structures  into  the  main  structure. 
For  instance,  a  car  may  be  drawn  by  using  commands  to  draw  the 
lines  which  represent  the  outlines  of  the  body  of  the  car,  and 
commands  to  pull  in  a  separate  structure  which  draws  a  wheel.  The 
wheel  structure  may  be  pulled  in  4  times,  once  for  each  wheel. 
Commands  may  be  included  which  reposition  the  wheel  structure  each 
time  it  is  used,  so  that  the  same  structure  used  for  the  left 
front  wheel  can  be  rotated  and  moved  to  the  correct  position  for 
the  right  rear  wheel,  etc. 

Once  the  structure  to  draw  a  picture  is  built,  that  structure 
can  be  displayed  on  a  workstation.  Usually,  a  workstation 
corresponds  to  a  physical  device  (e.g.,  a  terminal  screen),  but. 
the  UI-PLUS  implementation  requires  the  user  to  reference  each  U 1 
window  as  a  workstation.  In  this  manner,  several  pictures  can  bo 
drawn  on  a  single  screen  at  the  same  time. 

More  detailed  information  about  PHIGS  is  contained  in  ANSI 
X3.144-198x,  Computer  Graphics  -  Programmer's  Hiera rchica 1 
Interactive  Graphics  System  (PHIGS)  Functional  Description.  Ibis 
user's  manual  will  explain  the  use  of  each  of  the  individual 
callable  routines  currently  in  place  for  use  with  UI-PLUS. 

The  UI-PLUS  implementation  of  PHIGS  3-D  graphics  consists 
entirely  of  routines  which  adhere  to  the  PHIGS  C  binding.  These 
PHIGS  routines  are  not  callable  from  Fortran  or  COBOL.  (While 
UI-PLUS  has  not  implemented  every  function  described  in  the  PHIGS 
standard,  all  functionality  which  has  been  implemented  by  UI-PIUG 
has  been  implemented  according  to  the  standard.)  The  PHIGS 
callable  routines  may  be  embedded  into  ADL  code.  This  is  done  in 
exactly  the  same  manner  as  C  code  is  embedded  in  ADL,  by  enelos i n- 1 
the  calls  between  the  special  characters  t{  and  %}.  The  roir  .r. 
that  it  is  permissible  to  embed  the  routines  into  ADL  is  that  t.tu 
ADL  will  be  translated  into  C  code  by  the  Application  Generator. 

The  examples  in  this  manual  are  written  in  C. 

The  appearance  of  an  ellipsis  (...)  signifies  that  furth<  r 
statements  may  appear  at  this  point  but  are  not  immediately 
necessary  to  the  specific  example. 
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Calls  which  are  necessary  to  the  specific  example  are  shown 
in  bold  face  type. 

All  calls  MUST  be  made  with  the  name  of  the  routine  in  lower 

case . 
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9.1  POPENPHIGS 


This  routine  is  used  to  allocate  and  initialize  the  PHIGS 
state  list.  The  error  file  specification  and  buffer  space  size 
are  recorded,  but  not  otherwise  used  in  the  UI-PLUS 
implementation.  All  PHIGS  errors  encountered  in  processing  are 
written  to  the  NTM  error  log.  The  program  must  call  INITFP  before 
opening  PHIGS. 

9.1.1  Calling  Sequence 
popenphigs (error_f ile , buf_size) ; 

9.1.2  Parameter  Descriptions 

NAME  I/O  TYPE  DESCRIPTION 


f - H 

ERROR_FILE 

h - H 

INPUT 

h - H 

Pchar* 

The  address  of  the  null-term¬ 
inated  string  which  specifies 
the  name  of  the  file  into 
which  the  errors  are  to  be 
logged  (see  footnote) . 

BUF_SIZE 

INPUT 

— 

Plong 

— 

A  4-byte  signed  integer  which 
specifies  the  size  (in  bytes) 
of  the  buffer  space  to  be 
reserved  for  the  error  file. 

FOOTNOTE:  The  UI-PLUS  implementation  of  PHIGS  automatically 

writes  all  PHIGS  errors  encountered  into  the  NTM  error  log.  The 
ERROR_FILE  and  BUF_SIZE  information  is  recorded,  but  not  otherwise 
used. 

9.1.3  Example 

Pchar  error^file[]  =  "filename"; 

Plong  buf_sTze  =  512;  ... 

initfp ( ) ;  ... 

popenphigs (error_f ile,  buf_size) ;  ... 
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9.2  PCLOSEPHIGS 


PCLOSEPHIGS  is  used  to  free  the  PHIGS  state  list  and  any 
other  dynamically  allocated  structures.  All  open  workstations 
must  be  closed  before  closing  PHIGS.  In  order  to  terminate  the 
application,  the  program  must  call  TERMFP . 

9.2.1  Calling  Sequence 
pclosephigs ( ) ; 

9.2.2  Parameter  Descriptions 
PCLOSEPHIGS  has  no  associated  arguments. 

9.2.3  Example 

Pchar  error  filef]  =  "filename"; 

Plong  buf_sTze  =  512;  ... 

initfp ( ) ;  ... 

popenphigs(error_file,  buf_size) ;  ... 

pcloseplr  s ( ) ;  ... 

termfp ( ) 
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9 . 3  POPENSTRUCT 


POPENSTRUCT  opens  the  specified  structure  so  that  elements 
(instructions)  may  be  added.  If  the  structure  has  not  yet  been 
created,  POPENSTRUCT  also  creates  the  structure.  Only  one 
structure  may  be  opened  at  a  time.  In  order  to  open  a  new 
structure,  the  currently  open  structure  (if  any)  must  be  closed. 

9.3.1  Calling  Sequence 

popenstruct (struct_id) ; 


9.3.2  Parameter  Descriptions 


NAME 

I/O 

TYPE 

DESCRIPTION 

STRUCT  ID 

INPUT 

Pint 

A  4-byte  signed  integer  which 

which  serves  as  the  identifier 
for  the  structure  to  be  opened. 

+ - + - 4- - + 


9.3.3  Example 


Pchar  error^file[]  =  "filename"; 

Plong  buf_sTze  =  512; 

Pint  struct_id  =  1;  ... 

initfp( ) ;  ... 

popenphigs (errorf ile,  bufsize) ;  ... 

popenstruct (struct_id) ;  ... 

pclosephigs ( ) ;  ... 
termfp()  > 
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9.4  PCLOSESTRUCT 


PCLOSESTRUCT  closes  the  currently  open  structure.  Only  one 
structure  may  be  open  at  a  time.  In  order  to  open  a  new 
structure,  the  currently  open  structure  (if  any)  must  be  closed. 

9.4.1  Calling  Sequence 
pclosestruct ( ) ; 

9.4.2  Parameter  Descriptions 


PCLOSESTRUCT  has  no  associated  arguments. 

9.4.3  Example 


Pchar  error^file[]  =  "filename"; 

Plong  bufsTze  =  512; 

Pint  struct_id  =  1 ;  ... 

initfp ()  ;  ... 

popenphigs (errorf ile,  buf_size) ;  . . . 
popenstruct (structid) ;  ... 
pclosestruct ( )  ;  ... 
pclosephigs ( ) ;  ... 

termfp ( ) ; 
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9 . 5  PEXECUTESTRUCT 

PEXECUTESTRUCT  inserts  an  execute  structure  element  (an 
instruction  which  points  to  another  structure)  into  the  currently 
open  structure.  When  the  structure  containing  the  execute 
structure  element  (the  "parent”  structure)  is  traversed,  at  the 
point  where  the  execute  structure  element  is  reached,  the 
traversal  state  list  for  the  parent  structure  is  saved,  and  the 
structure  pointed  to  (the  "child"  structure)  is  completely 
traversed  using  the  child  structure's  traversal  state  list.  When 
the  child  structure  traversal  is  complete,  the  original  traversal 
state  list  is  restored,  and  traversal  of  the  parent  structure  is 
continued  from  the  point  where  it  left  off. 

For  example,  if  in  order  to  create  a  structure  which  draws  a 
car,  there  may  be  several  instructions  to  draw  different  parts  of 
the  car,  and  another  structure  which  draws  wheels.  Included  in 
the  structure  for  the  car  would  be  instructions  to  draw  the  doors, 
hood,  fenders,  etc.,  and  an  execute  structure  element  instruction 
which,  in  effect,  says  "execute  the  structure  which  draws  a 
wheel".  This  execute  structure  element  would  appear  four  times  in 
the  car  structure  in  order  to  draw  four  wheels. 


9.5.1  Calling  Sequence 
pexecutestruct (structid) ; 

9.5.2  Parameter  Descriptions 


NAME  I/O  TYPE  DESCRIPTION 


+ - + - + - + 


STRUCT_ID 

INPUT 

Pint 

+ - + - + - + 


- 1- 

A  4-byte  signed  integer  which 
specifies  the  child  structure 
to  be  traversed. 

- + 
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9.5.3  Example 

Pchar  error^f ile[ ]  =  "filename"; 

Plong  buf_sTze  =  512; 

Pint  struct_idl  =  1; 

Pint  struct_id2  -2;  ... 

initfp ( ) i  ;  ... 

popenphigs (error_f ile,  buf_size) ;  ... 
popenstruct (structidl) ;  ... 
pexecutestruct (struct_id2 ) ;  ... 
pclosestruct ( ) ;  ... 
pclosephigs ( ) ;  ... 

termfp() ; 
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9 . 6  PDELSTRUCT 


PDELSTRUCT  unposts  the  specified  structure  from  all 
workstations  and  deletes  the  specified  structure  and  all 
references  to  it  from  memory.  If  the  specified  structure  is 
currently  open,  it  is  closed  prior  to  deletion  and  re-opened 
afterward. 

9.6.1  Calling  Sequence 
pdelstruct (struct_id) ; 

9.6.2  Parameter  Descriptions 

NAME  I/O  TYPE  DESCRIPTION 


- 

STRUCT_ID 

y - h 

INPUT 

y - h 

Pint 

A  4-byte  signed  integer 

which 

specifies  the  structure 

to  be 

- H 

y - h 

y - 1 

deleted . 

9.6.3  Example 

Pchar  error^file[]  =  "filename"; 

Plong  buf_sTze  =  512; 

Pint  struct_idl  =  1; 

Pint  struct_id2  -2;  ... 

initfp ( ) i  ;  ... 

popenphigs (error_f ile,  buf_size) ;  ... 
popenstruct (struct_idl ) ;  ... 
pexecutestruct (struct_id2) ;  ... 
pclosestruct ( ) ;  ... 
pdelstruct (structidl) ;  ... 
pclosephigs ( ) ;  ... 
termfp ( ) ; 
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9.7  PDELSTRUCTNET 

PDELSTRUCTNET  unposts  the  specified  structure  together  with 
all  of  its  child  structures  (depending  upon  the  reference  flag) , 
from  all  workstations,  and  deletes  the  specified  structure  and  all 
references  to  it  from  memory.  Any  structure  in  the  specified 
network  that  is  currently  open  is  closed. 


9.7.1  Calling  Sequence 


pdelstructnet (struct_id ,  ref_flag) ; 


9.7.2  Parameter  Descriptions 


NAME  I/O  TYPE  DESCRIPTION 

- —  —  —  —  —  —  —  — - —  —  +  —  — - h  — - —  — - — 

STRUCT_ID  INPUT  Pint  A  4-byte  signed  integer  which 

specifies  the  structure  which 
is  to  be  deleted. 

+  — - —  —  —  —  —  —  —  —  —  —  —  —  —  —  —  — - — - 1 - - - —  — - —  —  —  — - — - 

REF_FLAG  INPUT  Preff  A  keyword  which  specifies 

whether  to  delete  child  struc¬ 
tures  which  are  referenced  by 
other  parent  structures. 

PDELETE  -  delete  the  parent 
structure  and  all  of  its  child 
structures,  even  if  the  child 
structures  are  referenced  by 
other  structures. 

PKEEP  -  delete  the  parent 
structure  and  all  of  the  child 
structures  which  are  not  ref¬ 
erenced  by  other  structures. 

+ - + - + - + - + 
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9.7.3  Example 

Consider  the  following  diagram: 


+  - 

Structure  3 

1 

(Auto  Body) 

Structure 

6 

Structure  1 

(Automobile) 

+  - 

(Tire) 

I 

Structure  5 

--  + 

+- 

(Wheel ) 

+  - 

Structure 

7 

(Hubcap) 

Structure 

6 

+  - 

Structure  5 

+  - 

(Tire) 

i 

(Wheel) 

--+ 

Structure  2 

(Pickup  Truck) 

--+ 

+  - 

Structure 

7 

1 

Structure  4 

(Hubcap) 

+  - 

(Pickup  Body) 

Structure  1  consists  of  the  commands  necessary  to  draw  an 
automobile,  which  include  the  command  to  reference  the  structure 
for  an  automobile  body  and  the  command  to  reference  the  structure 
for  a  wheel,  which  consists  of  the  commands  to  reference 
structures  for  a  tire  and  a  hubcap. 

Structure  2  consists  of  the  commands  necessary  to  draw  a 
pickup  truck,  which  include  the  command  to  reference  the  structure 
for  a  pickup  truck  body  and  the  command  to  reference  the  structure 
for  a  wheel,  which  consists  of  the  commands  to  reference 
structures  for  a  tire  and  a  hubcap. 

PDELSTRUCTNET ( 1 ,  PKEEP) ;  deletes  structure  1  and  structure  3. 
Structures  5,  6,  and  7  are  not  deleted  because  they  are  referenced 
by  structure  2. 

PDELSTRUCTNET ( 2 ,  PDELETE) ;  deletes  structures  2,  4,  5,  6,  and 
7,  regardless  of  the  fact  that  structures  5,  6,  and  7  are 
referenced  by  structure  1.  This  means  that  if  structure  1  is 
posted  after  the  PDELSTRUCTNET  call,  the  automobile  body  will 
appear  without  any  wheels,  since  the  structures  for  the  wheels 
have  been  deleted. 


9-11 


UM  620344200 
30  September  1990 

PDELALLSTRUCT 


9 . 8  PDELALLSTRUCT 

PDELALLSTRUCT  is  used  to  delete  all  structures  from  memory  at 
the  same  time.  Any  open  structure  is  closed  prior  to  deletion. 

9.8.1  Calling  Sequence 
pdelallstruct ( ) ; 

9.8.2  Parameter  Descriptions 
PDELALLSTRUCT  has  no  associated  arguments. 

9.8.3  Example 

Pchar  error  file[]  =  "filename"; 

Plong  buf_sTze  =  512; 

Pint  struct_idl  =  1; 

Pint  struct_id2  -2;  ... 

initfp ( )  ;  ... 

popenphigs (error_f ile,  buf_size) ;  ... 

popenstruct (struct_idl) ;  ... 

pexecutestruct (struct_id2) ;  ... 

pclosestruct ( ) ;  ... 

pdelallstruct () ;  ... 

pclosephigs ( )  ;  ... 

termfp ( ) ; 
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9.9  PP0LYLINE3 

PPOLYLINE3  is  used  to  insert  a  three  dimensional  polyline 
primitive  element  into  the  currently  open  structure.  During 
traversal,  a  connected  sequence  of  straight  lines  starting  at  thi 
first  point  specified  and  ending  at  the  last  point  specified  is 
generated . 

9.9.1  Calling  Sequence 

ppolyl ine3 ( num_points ,  points); 

9.9.2  Parameter  Descriptions 

NAME  I/O  TYPE  DESCRIPTION 


- H 

NUM_POINTS 

- H 

INPUT 

- - H 

Pint 

i 

b - 

An  integer  which  specifies 
the  number  of  points  to  be 
defined  by  the  points  argu¬ 
ment  . 

POINTS 

- H 

INPUT 

b - H 

Ppoint 3  * 

b - - 

The  address  of  the  first 
point  specified  in  the  ar¬ 
ray  of  points  which  will 
define  the  polyline. 

9.9.3  Example 

Pint  num_points  =  3 ; 

Ppoint3  points[]  =  {  {  0,  0,  0  }, 

{  1,  1,  1  >, 

(0,1,0)  > ; 

Pchar  error^file[]  =  "filename"; 

Plong  buf_slze  =  512; 

Pint  struct_id  =1;  ... 

init fp ( ) ;  ... 

popenphigs ( errorf i le ,  buf_si^e) ;  ... 

popenstruct ( struct  id)  ;  ... 

ppolyl ine3 (num_points ,  points);  ... 

pclosestruct ( )  ;  ... 

pclosephigs ( ) ;  ... 

termf p ( ) ; 
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9.10  PPOLYLINE 

PPOLYLINE  inserts  a  two  dimensional  polyline  primitive 
element  into  the  currently  open  structure.  During  traversal,  a 
connected  sequence  of  straight  lines  starting  at  the  first  point 
and  ending  at  the  last  point  is  generated. 

9.10.1  Calling  Sequence 
ppolyline (num_points,  points); 

9.10.2  Parameter  Descriptions 

NAME  I/O  TYPE  DESCRIPTION 

^  - —  -j - + - - f 


NUM_POINTS 

INPUT 

Pint 

An  integer  which  specifies 
the  number  of  points  to  be 
defined  by  the  points  argu¬ 
ment  . 

POINTS 

INPUT 

h - H 

Ppoint* 

h - H 

The  address  of  the  first 
point  specified  in  the  ar¬ 
ray  of  points  which  define 
the  polyline. 

9.10.3  Example 

Pint  num_points  =  3 ; 

Ppoint  points []  -  {  {  0,  0  }, 

{  1,  1  }, 

{  0,  1  }  }; 

Pchar  error^file[]  =  "filename”; 

Plong  buf_sTze  =  512; 

Pint  structid  =1;  ... 

initfp ( ) ;  ... 

popenphigs(error_file,  buf_size) ;  ... 

popenstruct (structid) ;  ... 

ppoly 1 ine ( num_points ,  points);  ... 

pclosestruct ( )  ;  ... 

pclosephigs ( ) ;  ... 

termf p ( ) ; 
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9.11  PPOLYMARKER3 


PPOLYMARKER3  will  cause  a  three  dimensional  polymarker 
primitive  element  to  be  inserted  into  the  currently  open 
structure.  During  traversal,  a  marker  is  generated  at  each  of  the 
points  specified  by  the  POINTS  argument. 

9.11.1  Calling  Sequence 
ppolymarker3 (num_points,  points) ; 

9.11.2  Parameter  Descriptions 

NAME  I/O  TYPE  DESCRIPTION 


NUM_POINTS 

h - H 

INPUT 

Pint 

An  integer  which  specifies 
the  number  of  points  to  be 
defined  by  the  points  argu¬ 
ment  . 

POINTS 

- H 

INPUT 

h - H 

Ppoint3* 

v - 

The  address  of  the  first 
point  specified  by  the  array 
of  points  which  will  define 
the  location(s)  of  the  poly¬ 
markers  . 

9.11.3  Example 

Pint  num_points  =  3 ; 

Ppoint3  points []  =  {  {  0,  0,  0  ), 

(1,1,1), 

{0,1,0}}; 

Pchar  error^file[]  =  "filename"; 

Plong  buf_sTze  =  512; 

Pint  struct_id  =1;  ... 

initfp ( ) ;  ... 

popenphigs(error_file,  buf_size) ;  ... 

popenstruct ( struct_id) ;  ... 
ppolymarker3 (num_points ,  points);  ... 
pclosestruct ( ) ;  ... 

pclosephigs ( ) ;  ... 
termfp ( ) ; 
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9.12  PPOLYMARKER 


PPOLYMARKER  causes  a  two  dimensional  polymarker  primitive 
element  to  be  inserted  into  the  currently  open  structure.  During 
traversal,  a  marker  is  generated  at  each  of  the  points  specified 
by  the  POINTS  argument. 


9.12.1  Calling  Sequence 


ppolymarker (num_points ,  points) ; 


9.12.2  Parameter  Descriptions 


NAME  I/O  TYPE  DESCRIPTION 


NUM_POINTS 

- H 

INPUT 

- 1 

Pint 

An  integer  which  specifies 
the  number  of  points  to  be 
defined  by  the  points  argu¬ 
ment  . 

POINTS 

+ - H 

INPUT 

h - H 

Ppoint* 

h - H 

The  address  of  the  first 
point  specified  by  the  array 
of  points  which  will  define 
the  location (s)  of  the  poly¬ 
marker  (s)  . 

9.12.3  Example 


Pint  num_points  =  3 ; 

Ppoint  points []  =  {  {  0,  0  ), 

{  1,  1  >, 

{  o,  l  )  }; 

Pchar  error^file[]  =  "filename"; 
Plong  buf_slze  =  512; 

Pint  struct  id  =  1 ;  ... 


initfp ( ) i  ;  ... 

popenphigs (error_f ile ,  buf_size) ;  ... 

popenstruct  (struct^_id)  ;  ... 

ppolymarker (num_poTnts,  points);  ... 
pclosestruct ( ) ;  ... 
pclosephigs ( ) ;  ... 

termfp ( ) ; 
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9.13  PTEXT3 


Causes  a  three  dimensional  text  primitive  element  to  be 
inserted  into  the  currently  open  structure.  During  traversal,  a 
character  string  is  generated  on  the  plane  specified  by  the 
arguments  'TEXT_PT'  and  'DIR'  relative  to  'TEXT_PT'. 

dir[0]  specifies  the  vector,  or  path  that  the  character 
string  is  to  follow.  dir[l]  specifies  which  direction  is  "up"  to 
the  character  string. 


9.13.1  Calling  Sequence 

ptext3 ( text_pt ,  dir,  text); 
9-13.2  Parameter  Descriptions 


NAME 


I/O 


•4 - - - - 1- 

Ppoint3* 


TEXT  PT 


INPUT 


+  - 


The  point  at  which  the  first 
character  of  the  text  string 
is  to  be  displayed. 


DIR 


INPUT 


Pvector3* 


An  array  of  two  three  dimen¬ 
sional  points.  The  first 
point  ( DIR [ 0 ] )  specifies  the 
direction  or  path  which  the 
text  string  is  to  follow. 

The  second  point  (DIR[lj) 
specifies  which  direction 
to  be  considered  "up"  for 
text  string.  Both  points 
relative  to  TEXT  PT,  that 
TEXT_PT  is  to  be  considered 
the  origin  when  specifying 
DIR,  regardless  of  TEXT_PT's 
actual  location. 


is 

the 

are 

is, 


TEXT 


INPUT 


Pchar* 


An  array  of  text  characters  j 
to  be  displayed  in  the  area  I 
specified  by  TEXT_PT  &  DIR. 
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9.13.3  Example 

Pchar  text[]  =  "Display  This  String"; 

Ppoint3  text_pt  =  {  4,  4,  4  }; 

Pvector3  dir[]  =  {  {  0,  1,  0  ), 

{  -1,  0,  0  >  }  ; 

Pchar  error___f  ile  [  ]  =  "filename"; 

Plong  buf_sTze  =  512; 

Pint  struct_id  =  1 ;  ... 

initfp ( ) ;  ... 

popenphigs (error_f ile,  buf_size) ;  ... 

popenstruct (struct_id) ;  ... 

ptext3 (text_pt ,  dir,  text);  ... 

pclosestruct ( )  ;  ... 

pclosephigs ( )  ;  ... 

termfp ( ) ; 

The  above  code  specifies  the  text  string  "Display  This 
String",  which  will  appear  starting  at  the  three  dimensional  point 
4,  4,  4,  proceeding  in  a  vertical  direction,  with  the  tops  of  the 
letters  pointing  directly  to  the  left.  By  manipulating  the  "up" 
direction,  the  text  can  be  rotated  in  three  dimensional  space.  By 
manipulating  the  path  direction,  the  direction  of  the  plane  upon 
which  the  text  string  will  lie  can  be  manipulated. 
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9.14  PTEXT 


This  routine  inserts  a  two  dimensional  text  primitive  element 
into  the  currently  open  structure.  During  traversal,  a  character- 
string  is  generated  on  the  Z  =  0  plane,  relative  to  TEXT_PT. 

9.14.1  Calling  Sequence 
ptext (text_pt ,  text); 

9.14.2  Parameter  Descriptions 

NAME  I/O  TYPE  DESCRIPTION 

+ - + - + - + - + 


TEXT_PT 

INPUT 

Ppo  Lnt* 

The  point  at  which  the  first 
character  of  the  text  string 
is  to  be  displayed. 

TEXT 

+ - H 

INPUT 

1- - H 

Pchar* 

1- - H 

An  array  of  text  characters 
which  are  to  be  displayed. 

9.14.3  Example 

Pchar  text[]  =  "Display  This  String"; 
Ppoint  text_pt  =  {  4,  4  }; 

Pchar  error^file[]  =  "filename"; 

Plong  buf_sTze  =  512; 

Pint  struct_id  =1;  ... 

initfp ( ) i  ;  ... 

popenphigs (error_f ile,  buf_size) ;  ... 

popenstruct (struct_idl) ;  ... 

ptext (text_pt,  text) ;  ... 

pclosestruct ( ) ;  ... 

pclosephigs ( ) ;  ... 

termfp ( ) ; 
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9 . 15  PFILLAREA3 

PFILLAREA3  is  used  to  insert  a  three  dimensional  fillarea 
primitive  into  the  currently  open  structure.  During  traversal, 
implicitly  closed  polygonal  area  is  generated. 

9.15.1  Calling  Sequence 

pf illarea3 (num_points,  points); 

9.15.2  Parameter  Descriptions 

NAME  I/O  TYPE  DESCRIPTION 


- H 

NUM_POINTS 

INPUT 

h - H 

Pint 

An  integer  which  specifies 
the  number  of  points  to  be 
defined  by  the  points  argu¬ 
ment  . 

POINTS 

INPUT 

h - - 

Ppoint3  * 

L. - 

The  address  of  the  first 
point  specified  by  the  array 
of  points  which  will  be  used 
to  define  the  boundaries  of 
the  fillarea. 

9.15.3  Example 

Pint  numpoints  =  8 ; 

Ppoint3  points []  =  (  {  0,  0,  0  }, 

{  1,  0,  0  }, 

{  1,  1,  0  }, 

{  0,  1,  0  ), 

{0,0,1), 

{  1,  0,  1  }, 

{  1,  1,  1  }, 

(0,1,1));  /*  A  cube  */ 

Pchar  error^file[]  =  "filename"; 

Plong  buf_sxze  =  512; 

Pint  struct_id  =1;  ... 
initfp ( ) i  ;  ... 

popenphigs (errorf ile,  buf_size) ;  ... 

popenstruct (struct_id) ;  ... 

pf illarea3 (num_points,  points);  ... 

pclosestruct ( ) ;  ... 

pclosephigs ( ) ;  ... 

termf p ( ) ; 


an 
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9.16  PFILLAREA 


PFILLAREA  is  used  to  insert  a  two  dimensional  lillarea 
primitive  element  into  the  currently  open  structure.  During 
traversal,  an  implicitly  closed  polygonal  area  is  generated. 


9.16.1  Calling  Sequence 

pf illarea (num_points ,  points); 

9.16.2  Parameter  Descriptions 


NAME  I/O  TYPE  DESCRIPTION 


- H 

NUM_POINTS 

h - - 

INPUT 

h - 

Pint 

An  integer  which  specifies 
the  number  of  points  to  be 
defined  by  the  points  argu¬ 
ment  . 

POINTS 

INPUT 

h - J 

Ppoint* 

h - 

The  address  of  the  first 
point  specified  by  the  array 
of  points  which  will  be  used 
to  define  the  boundaries  of 
the  fillarea. 

9.16.3  Example 

Pint  numpoints  =  4 ; 
Ppoint  points []  =  { 

{ 

{ 

{ 

Pchar  error^file[]  = 
Plong  buf_sTze  =  512 
Pint  struct  id  =  1; 


0,  0  }, 

1,  0  ), 

1,  1  ), 

0,  1  )  };  /*  A  square  */ 

" filename" ; 


initfp ( )  ;  ... 

popenphigs (error_f ile,  buf_size)  ;  ... 

popenstruct ( struct_id) ;  ... 

pf illarea (num_points ,  points);  ... 

pclosestruct ( ) ;  ... 

pclosephigs ( )  ;  ... 

termfp ( ) ; 
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9.17  POPENWS 


POPENWS  adds  a  page  to  the  window  which  is  specified  by  the 
argument  CONN_ID.  and  the  workstation  is  identified  by  the  integer 
specified  for  the  argument  WS .  If  a  workstation  WS  already 
exists,  an  error  is  reported.  POPENWS  also  allocates  and 
initializes  a  workstation  state  list  and  a  workstation  description 
table.  (NOTE:  The  argument  WS_TYPE  must  be  specified,  but  it  is 
ignored) . 

9.17.1  Calling  Sequence 
popenws(ws,  conn_id,  ws_type) ; 

9.17.2  Parameter  Descriptions 


NAME  I/O  TYPE  DESCRIPTION 

WS 

INPUT 

Pint 

A  4-byte  signed  integer  that 
is  an  identifier  for  the  work¬ 
station  being  opened. 

CONNID 

INPUT 

Pconnid 

A  C-language  structure  which 
contains  the  unique  path  name 
of  the  window  to  which  the 
page  containing  the  work¬ 
station  being  created  is  added 

WS_TYPE 

- H 

INPUT 

1- - H 

Pwstype 

f- - H 

A  C-language  structure  which 
also  contains  the  unique  path 
name  of  the  window  to  which 
the  page  containing  the  work¬ 
station  is  to  be  added.  (This 

argument  currently  is  ignored) 

i - 
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9.17.3  Example 


Pint  num_points  =  4 ; 

Ppoint  points []  =  {  {  0,  0  >, 

{  1,  0  }, 

{  1,  1  ), 

{  0,  1  }  };  /*  A  square  */ 

Pchar  error^file[]  =  "filename"; 

Plong  buf_slze  =  512; 

Pint  struct_id  =  1; 

Pint  ws  =  1; 

Pconnid  conn_id  =  "wl.fl.w2"; 

Pwstype  ws_type  =  "wl.fl.w2";  ... 


initfp ( ) i  ;  ... 

popenphigs (error_f ile ,  buf_size) ; 
popenstruct (struct_id) ;  ... 
pf illarea (num_points ,  points);  ... 
pclosestruct ( ) ;  ... 

popenws(ws,  conn_id,  ws_type) ; 
pclosephigs ( ) ;  ... 
termfp ( ) ; 
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9.18  PCLOSEWS 


PCLOSEWS  unposts  any  structures  which  are  currently  posted  on 
the  specified  workstation,  frees  the  workstation  state  list  and 
description  table,  and  removes  the  workstation  page  from  the 
window  in  which  it  was  opened. 

9.18.1  Calling  Sequence 

pclosews (ws) ; 


9.18.2  Parameter  Descriptions 

NAME  I/O  TYPE  DESCRIPTION 


WS 


:nput 


Pint 


A  4-byte  signed  integer  which  acts  j 
as  an  identifier  for  the  workstation 
which  is  to  be  closed. 


■  + 


9.18.3  Example 

Pint  num_points  =  4 ; 

Ppoint  points []  =  {  {  0,  0  }, 

{  1,  0  }, 

<  1,  1  }, 

{0,1));  /*  A  square  */ 

Pchar  error^file[]  =  "filename"; 

Plong  buf_sxze  =  512; 

Pint  struct_id  =  1; 

Pint  ws  =  1; 

Pconnid  conn_id  =  "wl.fl.w2"; 

Pwstype  ws_type  =  "wl.fl.w2";  ... 

initfp ( ) ;  ... 

popenphigs (errorf ile ,  buf_size) ;  ... 

popenstruct (struct_id) ;  ... 

pf illarea (num_points ,  points);  ... 

pclosestruct ( ) ;  ... 

popenws(ws,  conn_id,  ws_type) ;  ... 

pclosews (ws) ;  ... 

pclosephigs ( ) ;  ... 

termfp ( ) ; 
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9.19  PPOSTSTRUCT 


PPOSTSTRUCT  causes  the  specified  structure  to  be  marked  as 
displayed  on  the  specified  workstation.  More  than  one  structure 
can  be  posted  to  the  same  workstation.  When  multiple  structures 
are  posted  to  one  workstation,  they  are  "stacked",  in  the  order  in 
which  they  are  posted,  much  as  pages  are  stacked  in  a  window.  A 
major  difference  is  that  while  a  page  in  a  window  is  opaque,  that 
is,  the  underlying  page  is  not  visible,  the  pages  in  a  workstation 
can  be  considered  transparent,  as  if  several  overhead  projector 
transparencies  had  been  stacked  on  top  of  one  another,  as 
illustrated  in  the  following  figure: 


+ - + 


+ - +3 

11  I 


+ — + 

12  1 


+ - + 


+ — + 


+ - + 


This  figure  contains  3  over¬ 
lapping  fillareas.  In  the 
figure,  structure  1  was 
posted  to  the  workstation 
first  and  therefore  appears  on 
the  bottom  of  the  stack.  2 
was  posted  second,  and  appears 
on  top  of  1.  3  was  posted  last 

and  appears  on  top. 

As  shown  in  the  figure,  those 
portions  of  structures  which  are 
not  directly  obscured  by  subse- 
equently  posted  structures  are 
still  visible,  just  like  a  stack 
of  overhead  projector  transpar¬ 
encies  . 


Posting  a  structure  to  a  workstation  automatically  causes 
that  structure  and  all  referenced  structures  within  its  structure 
network  to  be  traversed. 


9.19.1  Calling  Sequence 

ppoststruct (ws ,  struct_id,  priority); 
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9.19.3  Example 


Pint  numpoints  =  4 ; 

Ppoint  points []  =  {  {  0,  0  }, 

{  1,  0  }, 

{  1,  1  ), 

(  0,  1  }  };  /*  A  square  */ 

Pchar  error^file[]  =  "filename"; 

Plong  buf_sxze  =  512; 

Pint  struct_id  =  1; 

Pint  ws  =  1; 

Pconnid  conn^id  =  "wl.fl.w2"; 

Pfloat  priority  =  1; 

Pwstype  ws_type  =  "wl.fl.w2";  ... 


initfp ( ) ;  ... 

popenphigs (error_f ile ,  buf_size) ;  ... 

popenstruct (struct_id) ;  ... 

pf illarea (num_points ,  points);  ... 

pclosestruct ( ) ;  ... 

popenws(ws,  conn_id,  ws^type) ;  ... 

ppoststruct (ws ,  struct_Td,  priority);  ... 

pclosews (ws) ;  ... 

pclosephigs ( ) ;  ... 

termfp ( ) ; 
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20.3  Examr 


Pint  num_points  =  4; 

Ppoint  points []  =  {  {  0,  0  }, 

{  1,  0  }, 

<  1,  1  >, 

{  0,  1  }  };  /*  A  square  */ 

Pchar  error  file[]  =  "filename"; 

Plong  buf_sTze  =  512; 

Pint  struct_id  =  1; 

Pint  ws  =  1; 

Pconnid  conn  id  =  "wl.fl.w2"; 

Pfloat  priority  =  1; 

Pwstype  ws_type  =  "wl.fl.w2" ;  ... 
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initfp ( ) i  ;  ... 

popenphigs (error_f ile,  buf_size) ;  ... 
popenstruct ( struct_id) ;  ... 
pfillarea(num_points,  points);  ... 
pclosestruct ( ) ;  ... 
popenws(ws,  conn_id,  ws^type) ;  ... 
ppoststruct (ws ,  struct_id,  priority);  ... 
punpoststruct (ws ,  struct_id) ;  ... 

pclosews(ws) ;  ... 
pclosephigs ( )  ;  ... 
termfp ( ) ; 
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9.21  PUNPOSTALLSTRUCT 


PUNPOSTALLSTRUCT  unposts  (removes)  all  structures  from  the 
specified  workstation.  The  structures  will  disappear  from  the 
screen  at  the  next  PREDRAWALLSTRUCT  or  PUPDATEWS. 

9.21.1  Calling  Sequence 
punpostallstruct (ws) ; 

9.21.2  Parameter  Descriptions 


NAME 


TYPE 


DESCRIPTION 


INPUT  Pint  A  4-byte  signed  integer  which 

specifies  the  workstation 
from  which  all  structures  are 
to  be  unposted,  or  removed. 


9.21.3  Example 


Pint  num_pointsl  =  4; 

Ppoint  pointsl[]  =  {  {  0,  0  ), 

(  1,  0  }, 

{  1,  1  >, 

{  0,  1  )  };  /*  A  square  */ 

Pint  num_points2  =  3 ; 

Ppoint  points2[]  =  {  {  0,  0  ), 

{  2,  0  ), 

{  1,  1  }  };  /*  A  triangle  */ 

Pchar  error^file[]  =  "filename"; 

Plong  buf_sTze  =  512; 

Pint  struct_idl  =  1; 

Pint  struct_id2  =  2; 

Pint  ws  =  1; 

Pconnid  conn^id  =  "wl.fl.w2"; 

Pfloat  priority  =  1; 

Pwstype  ws_type  =  "wl.fl.w2";  ... 
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initfp ( ) ;  ... 

popenphigs (error_f ile,  buf_size) ;  ... 

popenstruct (struct_idl) ;  ... 

pf illarea (num_pointsl ,  pointsl) ;  ... 

pclosestruct ( ) ;  ... 

popenstruct (struct_id2 ) ;  ... 

pfillarea (num_points2 ,  points2);  ... 

pclosestruct ( ) ;  ... 

popenws(ws,  conn_id,  ws  type);  ... 

ppoststruct (ws ,  struct_Idl,  priority);  ... 

ppoststruct (ws,  struct_id2,  priority);  ... 

punpostallstruct (ws) ;  ... 

pclosews (ws) ;  ... 

pclosephigs ( ) ;  ... 

termfp ( ) ; 
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9.22  PMSG 


PMSG  is  used  to  display  a  message  in  the  message  line  of  the 
UI-PLUS  screen.  PMSG  will  move  the  specified  message  into  the 
buffer.  If  the  message  is  to  be  displayed  immediately,  follow  the 
PMSG  call  with  an  OUTSCR  call.  If  the  specified  character  string 
is  longer  than  60  characters,  the  string  will  be  segmented  into  a 
series  of  60  character  (or  less)  strings.  When  the  message  queue 
is  viewed,  the  series  of  strings  will  be  inverted.  For  example, 
if  the  string  "This  is  a  character  string  which  is  to  be  displayed 
in  the  message  queue  via  the  call  PMSG.  It  is  longer  than  60 
characters,  so  it  will  appear  inverted  in  the  message  queue."  is 
specified,  the  following  will  appear  in  the  message  queue: 

ters,  so  it  will  appear  inverted  in  the  message  queue, 
essage  queue  via  the  call  PMSG.  It  is  longer  than  60  charac 
This  is  a  character  string  which  is  to  be  displayed  in  the  m 

9.22.1  Calling  Sequence 
pmsg(ws,  msg) ; 

9.22.2  Parameter  Descriptions 


NAME  I/O  TYPE  DESCRIPTION 


- H 

ws 

h - H 

INPUT 

h - H 

Pint 

A  4-byte  signed  integer  which  spec¬ 
ifies  the  workstation  to  which  the 
message  applies.  At  the  current 
time,  ws  is  recorded  but  ignored. 

MSG 

INPUT 

k - H 

Pchar* 

L - 

The  address  of  the  array  which  con¬ 
tains  the  character  string  which  is 
to  be  displayed. 
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9.22.3  Example 

Pint  num_points  =  4 ; 

Ppoint  points []  =  {  {  0,  0  }, 

{  1,  0  }, 

{  l,  1  >, 

{  0,  1  }  };  /*  A  square  */ 

Pchar  error_file[]  =  "filename"; 

Pchar  msg[]  =  "Your  message  here!"; 

Plong  buf_size  =  512; 

Pint  struct_id  =  1 ; 

Pint  ws  =  1 ; 

Pconnid  conn  id  =  "wl.fl.w2"; 

Pfloat  priority  =  1; 

Pwstype  ws_type  =  "wl . f 1 . w2" ;  ... 

initfp ( ) ;  ... 

popenphigs (error_f ile,  buf_size) ;  ... 
popenstruct (struct_id) ;  ... 
pf illarea (num_points ,  points);  ... 
pclosestruct ( ) ;  ... 
popenws(ws,  connid,  wstype) ;  ... 
pmsg(ws,  msg) ;  ... 

ppoststruct (ws ,  struct_id,  priority);  ... 
punpoststruct (ws ,  struct_id) ;  ... 
pclosews (ws) ;  . . . 
pclosephigs ( ) ;  ... 
termfp( ) ; 
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9.23  PSETLINETYPE 


This  routine  is  used  to  insert  a  set  linetype  element  into 
the  currently  open  structure.  During  traversal,  this  element  will 
set  the  linetype  entry  in  the  traversal  state  list  which  then 
effects  all  subsequent  polyline  primitives,  until  another  set 
linetype  element  is  encountered. 

This  process  is  similar  to  the  process  of  creating  an 
attribute  with  business  graphs.  The  difference  is  that  attributes 
are  tied  to  the  primitive  when  using  business  graphs,  but  the 
"attribute",  or  set  linetype  element,  is  tied  to  the  structure, 
not  just  one  primitive,  such  that  all  primitives  encountered  in 
the  structure  use  this  characteristic,  until  a  new  set  linetype 
element  (if  any)  is  encountered. 

9.23.1  Calling  Sequence 

psetlinetype ( linetype) ; 


23.2  Parameter  Descriptions 

NAME 

I/O 

TYPE 

DESCRIPTION 

LINETYPE 

INPUT 

h - 1 

Pint 

h - 

A  4-byte  signed  integer  which 
specifies  the  linetype  to  apply 
to  all  subsequent  polylines  in 
the  currently  open  structure. 
Available  linetypes  are: 

1  -  SOLID,  2  -  DASH,  3  -  DOT, 

4  -  DOTDASH 

h - 
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9.23.3  Example 

Pint  linetype  =1;  /*  Solid  line  */ 

Pint  num_points  =4; 

Ppoint  points []  =  {  {  0,  0  }, 

{  1,  0  }, 

{  1,  1  >, 

{  0,  1  }  };  /*  A  square  */ 

Pchar  error_file[]  =  "filename"; 

Pchar  msg[ ]  =  "Your  message  here!"; 

Plong  buf_size  =  512; 

Pint  structid  =  1; 

Pint  ws  =  1 ; 

Pconnid  conn^id  =  "wl.fl.w2"; 

Pfloat  priority  =  1; 

Pwstype  ws_type  =  "wl.fl.w2";  ... 

initfp( ) ;  ... 

popenphigs (error_f ile,  buf_size) ;  ... 

popenstruct (struct_id) ;  ... 

psetlinetype ( linetype) ;  ... 
ppolyline (numpoints,  points);  ... 
pclosestruct ( ) ;  ... 
popenws(ws,  connid,  ws_type) ;  ... 
pmsg(ws,  msg) ;  ... 

ppoststruct (ws ,  struct_id,  priority);  ... 
punpoststruct (ws,  struct_id) ;  ... 
pclosews (ws) ;  ... 
pclosephigs ( ) ;  ... 

termfp ( ) ; 
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9.24  PSETLINECOLOURIND 

This  routine  is  used  to  insert  a  set  polyline  color  index 
element  into  the  currently  open  structure.  During  traversal,  this 
element  will  set  the  polyline  color  entry  in  the  traversal  state 
list  which  then  effects  all  subsequent  polyline  primitives,  until 
a  new  set  line  color  index  element  is  encountered. 

This  process  is  similar  to  process  of  creating  an  attribute 
with  business  graphs.  The  difference  is  that  attributes  are  tied 
to  the  primitive  when  using  business  graphs,  but  the  "attribute", 
or,  in  this  case,  the  set  polyline  color  element,  is  tied  to  the 
structure,  not  just  one  primitive,  such  that  all  primitives 
encountered  in  the  structure  use  this  characteristic,  until  a  new 
set  polyline  color  element  (if  any)  is  encountered. 

9.24.1  Calling  Sequence 

psetlinecolourind ( index) ; 


23.2  Parameter 

Descriptions 

NAME 

I/O 

TYPE 

DESCRIPTION 

INDEX 

- H 

INPUT 

1- - H 

Pint 

i- - 1 

A  4-byte  signed  integer  which  spe¬ 
cifies  the  color  to  apply  to  all 
subsequent  polylines  in  the 
currently  open  structure. 

Available  colors  are: 

0  -  BLACK,  1  -  RED,  2  -  GREEN, 

3  -  YELLOW,  4  -  BLUE,  5  -  MAGENTA, 

6  -  CYAN,  7  -  WHITE 
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Pint  linetype  =  1;  /*  Solid  line 

Pint  index  =4;  /*  Blue  line 

Pint  num_points  =  4; 

Ppoint  points[]  =  {  {  0,  0  }, 

{  1,  0  }, 

<  1,  1  >, 

{  o,  1  >  };  /* 

Pchar  error_file[]  =  "filename"; 

Pchar  msg[]  =  "Your  message  here!"; 
Plong  bufsize  =  512; 

Pint  structid  =  1; 

Pint  ws  =  1; 

Pconnid  conn  id  =  "wl . f 1 . w2" ; 

Pfloat  priority  =  1; 

Pwstype  ws_type  =  "wl.fl.w2";  ... 

initfp ( ) i  ;  ... 

popenphigs (errorf ile,  buf_size) ;  ... 
popenstruct (structid) ;  ... 
psetlinetype ( 1 inetype) ;  ... 

psetlinecolourind ( index) ;  ... 

ppolyline (nura_pointr ,  points);  ... 
pclosestruct ( ) ;  ... 
popenws(ws,  conn_id,  ws_type) ;  ... 
pmsg(ws,  msg) ;  ... 

ppoststruct (ws,  structid,  priority); 
punpoststruct (ws ,  struct_id) ;  ... 
pclosews(ws) ;  ... 
pclosephigs ( ) ;  ... 
termfp ( ) ; 


PSETLINECOLOURIND 


*/ 

*/ 


A  square  */ 
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9.25  PSETMARKERTYPE 


PSETMARKERTYPE  inserts  a  set  marker  type  element  into  the 
currently  open  structure.  During  traversal,  this  element  will  set 
the  marker  type  entry  in  the  traversal  state  list  which  will 
effect  all  subsequent  marker  primitives,  until  another  set  marker 
type  element  is  encountered. 

9.25.1  Calling  Sequence 
psetmarkertype (markertype) ; 

9.25.2  Parameter  Descriptions 

NAME  I/O  TYPE  DESCRIPTION 


+ - H 

MARKERTYPE 

b - - 

INPUT 

b - H 

Pint 

b - + 

A  4-byte  signed  integer  which 

+ - . 

l- - - 

b - - 

specifies  the  type  of  marker 
to  use  each  time  a  polymarker 
is  encountered,  until  a  new 
set  polymarker  type  element  is 
encountered.  Valid  polymarker 
types  are: 

1  -  POINT  2  -  PLUS  3  -  STAR 

4  -  CIRCLE  5  -  CROSS 

9-37 


UM  620344200 
30  September  1990 

PSETMARKERTYPE 


9.25.3  Example 

Pint  markertype  -2;  /*  Polymarker  is  a  +  */ 

Pint  num_points  =4; 

Ppoint  points []  =  {  {  0,  0  }, 

{  1,  0  }, 

{  1,  1  >, 

{  0,  1  }  };  /*  A  square  with  a 

plus  (  +  )  at  each 
corner,  no  lines 
connecting.  */ 

Pchar  error_file[]  =  "filename"; 

Pchar  msg[]  =  "Your  message  here!"; 

Plong  buf_size  =  512; 

Pint  struct_id  =  1 ; 

Pint  ws  =  1 ; 

Pconnid  conn  id  =  "wl.fl.w2"; 

Pfloat  priority  =  1; 

Pwstype  ws_type  =  "wl.fl.w2";  ... 

initfp ( ) ;  ... 

popenphigs (error_f ile,  buf_size) ;  ... 
popenstruct (structid) ;  ... 
psetmarkertype (markertype) ;  ... 
ppolymarker (num  points ,  points);  ... 
pclosestruct ( ) ;  ... 
popenws(ws,  conn_id,  ws_type) ;  ... 
pmsg (ws,  msg) ;  . . . 

ppoststruct (ws,  struct_id,  priority);  ... 
punpoststruct (ws ,  struct_id) ;  ... 
pclosews(ws) ;  ... 
pclosephigs ( ) ;  ... 
termfp ( ) ; 
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9.26  PSETMARKERCOLOURIND 

PSETMARKERCOLOURIND  inserts  a  set  polymarker  color  index 
element  into  the  currently  open  structure.  During  traversal,  thi 
element  will  set  the  marker  type  entry  in  the  traversal  state  lis 
which  effects  subsequent  marker  primitives  until  a  new  set 
polymarker  color  index  element  is  encountered. 

9.26.1  Calling  Sequence 

psetmarkercolourind ( index) ; 


.26.2  Parameter 

Descriptions 

NAME 

I/O 

TYPE 

DESCRIPTION 

INDEX 

■4 - i 

INPUT 

Pint 

A  4-byte  signed  integer  which  spe¬ 
cifies  the  color  to  apply  to  all 
subsequent  polymarkers  in  the 
currently  open  structure. 

Available  colors  are: 

0  -  BLACK,  1  -  RED,  2  -  GREEN, 

3  -  YELLOW,  4  -  BLUE,  5  -  MAGENTA 

6  -  CYAN,  7  -  WHITE 
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Pint  markertype  =2;  /*  Polymarker  is  a  +  */ 

Pint  index  =6;  /*  Polymarker  color  is  magenta  */ 

Pint  num_points  =  4 ; 

Ppoint  points []  =  {  {  o,  o  }, 

{  1,  0  }, 

{  1,  1  }, 

{  o,  1  }  };  /*  A  square  with  plus 

signs  at  each  corner, 
no  connecting  lines, 
color  is  magenta  */ 

Pchar  error_file[]  =  "filename"; 

Pchar  msg[]  =  "Your  message  here!"; 

Plong  bufsize  =  512; 

Pint  struct_id  =  l; 

Pint  ws  =  1; 

Pconnid  conn^id  =  "wl.fl.w2"; 

Pfloat  priorTty  =  l; 

Pwstype  ws_type  =  "wl.fl.w2";  ... 

initfp ( ) i  ;  ... 

popenphigs (error_f ile ,  buf_size) ;  ... 
popenstruct ( structid) ;  ... 
psetmarkertype (markertype) ;  ... 
psetmarkercolourind ( index)  ;  ... 
ppolymarker (numpoints,  points);  ... 
pclosestruct ( ) ;  ... 
popenws (ws ,  connid,  wstype) ;  ... 
pmsg(ws,  msg) ;  ... 

ppoststruct (ws,  struct_id ,  priority);  ... 
punpoststruct (ws,  struct_id) ;  ... 
pclosews (ws) ;  ... 
pclosephigs ( ) ;  ... 
termfp ( ) ; 
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9.27  PSETTEXTCOLOURIND 

This  routine  is  used  to  insert  a  set  text  color  index  element 
into  the  currently  open  structure.  During  traversal,  this  element 
will  set  the  text  color  entry  in  the  traversal  state  list  which 
effects  all  subsequent  text  primitives  until  a  new  set  text  color 
index  element  is  encountered. 

9.27.1  Calling  Sequence 
psettextcolourind ( index) ; 

9.27.2  Parameter  Descriptions 

NAME  I/O  TYPE  DESCRIPTION 


INDEX 

INPUT 

Pint 

A  4-byte  signed  integer  which  spe¬ 
cifies  the  color  to  apply  to  all 

subsequent  appearances  of  text  in 
the  currently  open  structure. 
Available  colors  are: 

i - 

1 - 

0  -  BLACK,  1  -  WHITE,  2  -  RED, 

3  -  GREEN,  4  -  BLUE,  5  -  CYAN, 

6  -  MAGENTA,  7  -  YELLOW 

9.27.3  Example 

Pint  index  = 3 ;  /*  Text  color  is  GREEN  */ 

Pchar  text[]  =  "Display  This  String"; 

Ppoint  textpt  =  {  4,  4  ); 

Pchar  error_file[]  -  "filename"; 

Pchar  msg[]  =  "Your  message  here!"; 

Plong  buf_size  =  512; 

Pint  struct_id  =  1; 

Pint  ws  =  1; 

Pconnid  conn  id  =  "wl.fl.w2"; 

Pfloat  priorTty  =  1; 

Pwstype  ws_type  =  "wl.fl.w2";  ... 
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initfp ( ) i  ;  ... 

popenphigs (error_f ile,  buf_siEe) ;  ... 

popenstruct ( struct^id) ;  ... 

psettextcolourind (Index) ;  ... 

ptext ( text_pt ,  text) . . . 
pclosestruct ( )  ;  ... 

popenws(ws,  conn_id,  ws_type) ;  ... 

pmsg(ws,  msg) ;  ... 

ppoststruct (ws ,  struct_id,  priority);  ... 
punpoststruct (ws ,  struct_id) ;  ... 

pclosews(ws) ;  ... 

pclosephigs ( ) ;  ... 
termfp ( ) ; 
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9.28  PSETCHARHEIGHT 


PSETCHARHEIGHT  inserts  a  set  character  height  element  into 
the  currently  open  structure.  During  traversal,  this  element  will 
set  the  character  height  entry  in  the  traversal  state  list  which 
effects  all  subsequent  text  primitives  until  the  next  set 
character  height  element  is  encountered. 

9.28.1  Calling  Sequence 

psetcharheight (height ) ; 


9.28.2  Parameter  Descriptions 


NAME 

I/O 

TYPE 

DESCRIPTION 

HEIGHT 

INPUT 

Pfloat 

A  floating  point  number  wh-iCt 
specifies  the  height  of  the  text 
characters  to  be  displayed.  The 
numbers  represent  a  scaling 
factor,  where  1  represents  a 
character  which  is  the  height  of 
the  display  space,  .10  repre¬ 
sents  one  tenth  the  height  of 
the  display  space,  and  so  on. 

+ - + - + - + - + 


9.28.3  Example 

Pfloat  height  =  .05  /*  5/100  of  the  display  space  */ 

Pint  index  =3;  /*  Text  color  is  GREEN  */ 

Pchar  text[]  =  "Display  This  String"; 

Ppoint  text_pt  =  {  4,  4  }; 

Pchar  error _file[]  =  "filename"; 

Pchar  msg [ ]  =  "Your  message  here!"; 

Plong  buf_size  =  512; 

Pint  struct_id  =  1; 

Pint  ws  =  1; 

Pconnid  conn  id  =  "wl.fl.w2"; 

Pfloat  priority  =  1; 

Pwstype  ws__type  =  "wl .  f  1 .  w2  "  ;  ... 
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initfp ( ) i  ;  ... 

popenphigs (error_f ile,  buf_size) ;  ... 
popenstruct  (struct^id)  ;  ... 
psettextcolourind (Index) ;  ... 
psetcharheight (height) ;  ... 

ptext (text_pt,  text) . . . 
pclosestruct ( ) ;  ... 

popenws(ws,  conn_id,  ws_type) ;  ... 

pmsg(ws,  msg) ;  ... 

ppoststruct (ws ,  struct_id,  priority);  ... 
punpoststruct (ws ,  struct_id) ;  ... 
pclosews(ws) ;  ... 

pclosephigs ( ) ;  ... 

termf p ( )  ; 
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2.29  PSETINTSTYLE 


PSETINTSTYLE  is  used  to  insert  a  set  interior  style  element 
into  the  current  open  structure.  During  traversal,  this  element 
will  set  the  interior  style  entry  in  the  traversal  state  list 
which  will  effect  all  subsequent  fill  area  primitives  until 
another  set  interior  style  element  is  encountered. 


2.29.1  Calling  Seguence 


psetintstyle (style) ; 


2.29.2  Parameter  Descriptions 


NAME  I/O  TYPE  DESCRIPTION 

■f - 1 - 1 - 1 - h 

STYLE  INPUT  Pinterstyle  A  C-language  structure  which 

contains  the  specifier  for 
the  type  of  interior  to 
assign  to  all  subsequent 
fillareas  in  the  currently 
open  structure.  The  avail¬ 
able  interior  styles  are: 

0  -  HOLLOW,  1  -  SOLID, 

2  -  PATTERN,  3  -  HATCH 

+ - 4- - + - + - + 


2.29.3  Example 


Pinterstyle  style  =  1;  /*  Interior  is  hollow  */ 

Pint  num_points  =  4 ; 

Ppoint  points []  =  {  {  0,  0  }, 

{  1,  0  ), 

<  1,  1  }, 

(  0 ,  1  }  } ;  /*  A  square  */ 

Pchar  error_file[]  =  "filename"; 

Pchar  msg[]  =  "Your  message  here!"; 

Plong  buf_size  =  512; 

Pint  struct_id  =  1; 

Pint  ws  =  1; 

Pconnid  conn  id  =  "wl.fl.w2”; 

Pfloat  priority  =  1; 

Pwstype  ws_type  =  "wl.fl.w2";  ... 
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initfp ( )  ;  ... 

popenphigs (error_f ile,  buf_size) ;  ... 
popenstruct (struct_id) ;  ... 
psetintstyle ( style) ;  ... 
pf illarea (num_points ,  points);  ... 
pclosestruct ( ) ;  ... 
popenws(ws,  conn_id,  ws_type) ;  ... 
pmsg(ws,  msg) ;  ... 

ppoststruct (ws ,  struct_id,  priority);  ... 
punpoststruct (ws,  struct_id) ;  ... 
pclosews(ws) ;  ... 
pclosephigs ( ) ;  ... 
termf p ( ) ; 
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9.30  PTRANSLATE3 

PTRANSLATE3  is  used  to  move  a  three  dimensional  structure  in 
a  workstation  to  another  position  within  the  workstation.  This  is 
accomplished  by  passing  in  the  vector  along  which  the  structure  is 
to  be  moved,  which  is  m  turn  used  to  construct  a  transformation 
matrix.  The  transformation  matrix  is  used  at  a  later  point  to 
actually  perform  the  move  with  the  routines  PTRANPT3 , 
PSETL0CALTRAN3 ,  and  PSETGL0BALTRAN3 . 

9.30.1  Calling  Sequence 

ptranslate3 (trans_vector ,  &err_ind,  matrix); 


9.30.2  Parameter  Descriptions 


NAME  I/O  TYPE  DESCRIPTION 

TRANS_VECTOR 

INPUT 

Pvector3  * 

The  vector  along  which 
the  structure  is  to  be 
moved.  This  is  an  array 
of  three  (x,y,z)  coord¬ 
inates  . 

ERR_IND 

OUTPUT 

Pint* 

An  integer  which  repre¬ 
sents  an  error  code. 

MATRIX 

+ - 1 

OUTPUT 

h - 1 

Pmatrix3 

A  4  X  4  matrix  which 
will  be  used  when  per- 
performing  the  trans¬ 
formation  . 

f. - 
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9.30.3  Example 

Pint  err_ind; 

Pvector3  trans_vector  =  {  5,  5,  5  };  /*  The  vector  along 

which  to  move  the 
structure  */ 

Pmatrix3  matrix;  /*  The  transformation  matrix  */ 

Pinterstyle  style  =  1;  /*  Interior  is  hollow  */ 

Pint  num_points  =8; 

Ppoint3  points []  =  (  {  0,  0,  0  }, 

{  1,  0,  0  }, 

{  1/  1,  0  }, 

{  0,  1,  0  }, 

{  0,  0,  1  }, 

{  1,  0,  1  }, 

{  1,  1,  1  }, 

{0,1,1}};  /*  A  cube  */ 

Pchar  error_file[]  =  "filename"; 

Pchar  msg[]  =  "Your  message  here!"; 

Plong  buf_size  =  512; 

Pint  struct_id  =  1 ; 

Pint  ws  =  1; 

Pconnid  conn^id  -  "wl.fl.w2"; 

Pfloat  priority  =  1; 

Pwstype  ws_type  =  "wl.fl.w2";  ... 

initfp( ) ;  ... 

popenphigs (error_f ile,  buf_size) ;  ... 
popenstruct (structid) ;  ... 
psetintstyle (style) ;  ... 
pf illarea3 (num_points ,  points);  ... 
pclosestruct ( ) ;  ... 
popenws(ws,  conn_id,  ws_type) ;  ... 
pmsg (ws ,  msg) ;  . . . 

ppoststruct (ws ,  struct_id,  priority);  ... 

ptranslate3 (trans_vector ,  &err_ind,  matrix);  ... 

punpoststruct (ws ,  struct_id) ;  ... 

pclosews (ws)  ;  .  .  . 

pclosephigs ( )  ;  ... 

termfp ( ) ; 


9-48 


UM  620344200 
30  September  1990 


PTRANSLATE 


9.31  PTRANSLATE 

PTRANSLATE  is  used  to  move  a  two  dimensional  structure  in  a 
workstation  to  another  position  within  the  workstation.  This  is 
accomplished  by  passing  in  the  vector  along  which  the  structure  is 
to  be  moved,  which  is  m  turn  used  to  construct  a  transformation 
matrix.  The  transformation  matrix  is  used  at  a  later  point  to 
actually  perform  the  move,  with  the  routines  PTRANPT , 
PSETLOCALTRAN,  and  PSETGLOBALTRAN . 

9.31.1  Calling  Sequence 


ptranslate(trans_vector,  &err_ind,  matrix) ; 


NAME 

I/O 

TYPE 

DESCRIPTION 

TRANS_VECTOR 

INPUT 

Pvector* 

The  vector  along  which 
the  structure  is  to  be 
moved.  Vector  is  an 
array  of  x-Y  coordinates. 

ERR_IND 

OUTPUT 

Pint* 

An  integer  which  repre¬ 
sents  an  error  code. 

MATRIX 

OUTPUT 

i - 

Pmatrix 

A  3  X  3  matrix  which  will 
be  used  when  performing 
the  transformation. 
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9.31.3  Example 

Pint  err_ind; 

Pvector  trans_vector  =  {  5,  5  ); 

Pmatrix  matrix; 

Pinterstyle  style  =  l;  /*  Interior  is  hollow  */ 
Pint  num_points  =  4; 

Ppoint  points []  =  {  {  o,  0  }, 

{  1,  0  }, 

{  1/  1 

{  0,  1  }  };  /*  A  square  */ 

Pchar  error_file[]  =  "filename"; 

Pchar  msg[]  =  "Your  message  here!"; 

Plong  buf_size  =  512; 

Pint  struct_id  =  1; 

Pint  ws  =  1 ; 

Pconnid  conn  id  =  "wl.fl.w2"; 

Pfloat  priority  =  1; 

Pwstype  ws_type  =  "wl.fl.w2";  ... 

initfp ( ) i  ;  ... 

popenphigs (error_f ile,  buf_size) ;  ... 

popenstruct (structid) ;  ... 

psetintstyle (style) ;  ... 

pf illarea(num_points,  points);  ... 

pclosestruct ( ) ;  ... 

popenws ( ws ,  conn^id,  ws_type) ;  ... 

pmsg(ws,  msg) ;  ... 

ppoststruct (ws,  struct_id ,  priority);  ... 
ptranslate (transvector ,  &err_ind,  matrix);  ... 
punpoststruct (ws,  struct_id) ;  ... 
pclosews(ws) ;  ... 
pclosephigs ( ) ;  ... 
termf p ( ) ; 
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9.32  PSCALE3 

PSCALE3  is  used  to  resize  a  three  dimensional  structure. 

This  is  accomplished  by  passing  in  the  vector  along  which  to 
resize  the  structure.  The  vector  is  specified  in  X-Y-Z 
coordinates.  The  numbers  specified  for  the  coordinates  are  the 
factors  by  which  to  multiply  in  order  to  get  the  new  size.  For 
example,  a  coordinate  set  of  1,  1,  1  would  not  change  the  size  of 
the  structure  at  all.  Coordinates  of  2,  1,  1  would  stretch  the 
structure  to  twice  its  width  along  the  X-axis.  Coordinates  of  1, 
.5,  2  would  shrink  the  structure  to  half  its  height  along  the 
Y-axis  and  stretch  the  structure  to  twice  its  depth  along  the 
Z-axis.  This  vector  is  used  to  construct  a  transformation  matrix. 
The  transformation  matrix  is  used  at  a  later  point  to  actually 
perform  the  resizing,  with  the  routines  PTRANPT3 ,  PSETL0CALTRAN3 , 
and  PSETGLOBALTRAN3 . 

9.32.1  Calling  Sequence 

pscale3 ( scale_vector ,  &err_ind,  matrix); 

9.32.2  Parameter  Descriptions 

NAME  I/O  TYPE  DESCRIPTION 


SCALE_ VECTOR 

INPUT 

h - H 

Pvector3  * 

The  vector  along  which 
the  structure  is  to  be 
resized.  It  is  given  as 
an  array  of  X-Y-Z  coord¬ 
inates  . 

ERR_IND 

OUTPUT 

Pint* 

An  integer  which  repre¬ 
sents  an  error  code. 

MATRIX 

- - 

OUTPUT 

h - H 

Pmatrix3 

A  4  X  4  matrix  which 
will  be  used  when  per- 
performing  the  trans¬ 
formation  . 

h - 
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9.32.3  Example 

Pint  err_ind; 

Pvector3  trans_vector  =  {  5,  5,  5  };  /*  Grow  the  structure 

by  a  factor  of  5 
in  all  directions 

*/ 

Pmatrix3  matrix;  /*  The  transformation  matrix  */ 

Pinterstyle  style  =1;  /*  Interior  is  hollow  */ 

Pint  num_points  =  8 ; 

Ppoint3  points []  =  {  {  0,  0,  0  }, 

{  1,  0,  0  >, 

{  1,  1,  0  }, 

{  0,  1,  0  }, 

{  0,  0,  1  }, 

{  1,  0,  1  }, 

{  1,  1,  1  ), 

{0,1,1}};  /*  A  cube  */ 

Pchar  error_file[]  =  "filename"; 

Pchar  msg[]  =  "Your  message  here!"; 

Plong  buf_size  =  512; 

Pint  struct_id  =  1; 

Pint  ws  =  1 ; 

Pconnid  conn  id  =  "wl.fl.w2"; 

Pfloat  priority  =  1; 

Pwstype  ws_type  =  "wl.fl.w2";  ... 

initfp ( ) i  ;  ... 

popenphigs(error_file,  buf_size) ;  ... 
popenstruct (struct_id) ;  ... 
psetintstyle (style) ;  ... 
pf illarea3 (num_points,  points);  ... 
pclosestruct ( ) ;  ... 
popenws(ws,  conn_id,  ws_type;;  ... 
pmsg(ws,  msg) ;  ... 

ppoststruct (ws,  struct_id,  priority);  ... 
pscale3 (trans_vector ,  &err_ind,  matrix);  ... 
punpoststruct (ws ,  struct_id) ;  ... 
pclosews (ws) ;  ... 
pclosephigs ( ) ;  ... 
termfp ( ) ; 
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9.33  PSCALE 

PSCALE  is  used  to  resize  a  two  dimensional  structure.  This 
is  accomplished  by  passing  in  the  vector  along  which  to  resize  the 
structure.  The  vector  is  specified  in  CST  coordinates.  The 
numbers  specified  for  the  coordinates  are  the  factors  by  which  to 
multiply  in  order  to  get  the  new  size.  For  example,  a  coordinate 
set  of  1,  1  would  not  change  the  size  of  the  structure  at  all. 
Coordinates  of  2,  1  would  stretch  the  structure  to  twice  its  width 
along  the  X-axis.  Coordinates  of  1,  .5  would  shrink  the  structure 

to  half  its  height  along  the  Y-axis.  This  vector  is  used  to 
construct  a  transformation  matrix.  The  transformation  matrix  is 
used  at  a  later  point  to  actually  perform  the  resizing,  with  the 
routines  PTRANPT ,  PSETLOCALTRAN ,  and  PSETGLOBALTRAN . 

9.33.1  Calling  Seguence 

pscale(scale_vector,  &err_ind,  matrix); 


9.33.2  Parameter  Descriptions 


NAME  I/O  TYPE  DESCRIPTION 

SCALE_VECTOR 

INPUT 

Pvector* 

The  vector  along  which 
the  structure  is  to  be 
resized.  The  vector  is 
specified  as  an  array  of 
X-Y  coordinates. 

ERR_IND 

OUTPUT 

Pint* 

An  integer  which  repre¬ 
sents  an  error  code. 

MATRIX 

+ - -] 

OUTPUT 

h - H 

Pmatrix 

h - H 

A  3  X  3  matrix  which 
will  be  used  when  per- 
performing  the  trans¬ 
formation  . 
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9.33.3  Example 


Pint  err_ind; 

Pvector  scale_vector  =  { 

5,  5  )  ; 

/* 

Grow  the  structure 

Pmatrix  matrix; 

/* 

by  a  factor  of  5 
in  all  directions  */ 
The  transformation 

Pinterstyle  style  =  1; 

/* 

matrix  */ 

Interior  is  hollow  */ 

Pint  num  points  =  4 ; 
Ppoint  points []  =  {  {  0, 

{  1 , 

{  1, 

{  o, 

0  }, 

0  }, 

1  }, 
i  )  ); 

/* 

A  square  */ 

Pchar  error_file[]  =  "filename"; 

Pchar  msg[]  =  "Your  message  here!"; 

Plong  bufsize  =  512; 

Pint  structid  =  1; 

Pint  ws  =  1; 

Pconnid  conn  id  =  "wl.fl.w2"; 

Pfloat  priority  =  1; 

Pwstype  ws_type  =  "wl.fl.w2";  ... 

initfp ( ) ;  ... 

popenphigs (error_f ile,  buf_size) ;  ... 
popenstruct (struct_id) ;  ... 
psetintstyle (style) ;  ... 
pf illarea (num_points ,  points);  ... 
pclosestruct ( ) ;  ... 
popenws(ws,  conn_id,  ws_type) ;  ... 
pmsg (ws ,  msg) ;  ... 

ppoststruct (ws ,  struct_id,  priority);  ... 
pscale (trans_vector ,  &err^ind,  matrix);  ... 
punpoststruct (ws ,  struct_Id) ;  ... 
pclosews (ws) ;  ... 
pclosephigs ( ) ;  ... 
termfp ( ) ; 
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9 . 34  PROTATEX 

PROTATEX  is  used  to  rotate  a  three  dimensional  structure 
around  the  X-axis.  PROTATEX  generates  the  three  dimensional 
transformation  matrix  which  will  be  used  to  perform  the  rotation. 

9.34.1  Calling  Sequence 

protatex (angle,  &err_ind,  matrix); 


NAME 

I/O 

TYPE 

DESCRIPTION 

ANGLE 

INPUT 

Pfloat 

A  float  point  number  which 
specifies  the  angle  of  ro¬ 
tation,  given  in  radians 
(there  are  2  *  pi  radians 
in  a  circle) .  A  positive 
number  rotates  the  struc¬ 
ture  counter-clockwise,  a 
negative  number  rotates  it 
clockwise . 

ERR_IND 

OUTPUT 

1 

Pint* 

An  integer  which  repre¬ 
sents  an  error  code. 

MATRIX 

OUTPUT 

Pmatrix3 

The  transformation  matrix 
which  will  be  used  to 
rotate  the  structure. 
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9.34.3  Example 

Pint  err_ind; 

Pfloat  angle  =  .5;  /*  Rotate  the  structure  by  one- 

half  of  a  radian  (about  29 
degrees)  */ 

Pmatrix3  matrix;  /*  The  transformation  matrix  */ 

Pinterstyle  style  =1;  /*  Interior  is  hollow  */ 

Pint  num_points  =  8; 

Ppoint3  points []  =  {  {  0,  0,  0  ), 

(  1,  0,  0  }, 

(  1,  1,  0  }, 

(0,1,0), 

{  0,  0,  1  }, 

{  1,  0,  1  }, 

{  1,  1,  1  }, 

{0,1,1});  /*  A  cube  */ 

Pchar  error_file[]  =  "filename"; 

Pchar  msg [ ]  =  "Your  message  here!"; 

Plong  buf_size  =  512; 

Pint  struct_id  =  1; 

Pint  ws  =  1; 

Pconnid  conn^id  =  "wl.fl.w2"; 

Pfloat  priority  =  1; 

Pwstype  ws_type  =  "wl.fl.w2";  ... 

initfp ( ) i  ;  ... 

popenphigs (error_f ile,  buf_size)  ;  ... 
popenstruct (structid) ;  ... 
psetintstyle (style)  ;  ... 
pf illarea (numpoints ,  points);  ... 
pclosestruct ( ) ;  ... 
popenws(ws,  conn_id,  ws_type) ;  ... 
pmsg (ws ,  msg) ;  ... 

ppoststruct (ws ,  struct_id,  priority);  ... 
protatex(angle,  &err_ind,  matrix);  ... 
punpoststruct (ws ,  struct_id) ;  ... 
pclosews (ws) ;  ... 
pclosephigs ( ) ;  ... 
termfp ( ) ; 
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9.35  PROTATEY 


PROTATEY  is  used  to  rotate  a  three  dimensional  structure 
around  the  Y-axis.  PROTATEY  generates  the  three  dimensional 
transformation  matrix  which  will  be  used  to  perform  the  rotation. 

9.35.1  Calling  Sequence 

protatey (angle,  &err_ind,  matrix); 

9.35.2  Parameter  Descriptions 


NAME  I/O  TYPE  DESCRIPTION 

ANGLE 

INPUT 

Pfloat 

A  float  point  number  which 
specifies  the  angle  of  ro¬ 
tation,  given  in  radians 
(there  are  2  *  pi  radians 
in  a  circle) .  A  positive 
number  rotates  the  struc¬ 
ture  counter-clockwise ,  a 
negative  number  rotates  it 
clockwise . 

ERR_IND 

i 

OUTPUT 

Pint* 

An  integer  which  repre¬ 
sents  an  error  code. 

MATRIX 

OUTPUT 

Pmatrix3 

The  transformation  matrix 
which  will  be  used  to 
rotate  the  structure. 

+ - + - + - + - + 
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9.35.3  Example 


Pint  err_ind; 
Pfloat  angle  =  .5; 


Pmatrix3  matrix; 
Pinterstyle  style  = 
Pint  num_points  =  8 ; 
Ppoint3  points []  =  { 


/* 

Rotate  the  structure  by  one- 
half  of  a  radian  (about  29 
degrees)  */ 

/* 

The  transformation  matrix  */ 

l; 

/* 

Interior  is  hollow  */ 

{ 

0 

,  0 

,  0  }, 

{ 

i, 

0, 

0  }, 

{ 

i, 

1, 

0  }, 

{ 

0, 

1, 

0  }, 

{ 

0, 

0, 

1  ), 

( 

1, 

0, 

1  ), 

( 

1, 

1, 

1  ), 

{ 

0, 

1, 

1  }  }  ;  /*  A  cube  */ 

Pchar  error_file[]  =  "filename"; 
Pchar  msg[]  =  "Your  message  here!"; 
Plong  buf_size  =  512; 

Pint  struct_id  =  1; 

Pint  ws  =  1; 

Pconnid  conn  id  =  "wl.fl.w2"; 

Pfloat  priority  =  1; 

Pwstype  ws_type  =  "wl.fl.w2";  ... 


initfp ( ) i  ;  ... 

popenphigs (error_f ile,  buf_size) ;  ... 
popenstruct (struct_id) ;  ... 

psetintstyle ( style)  ;  ... 
pf illarea (num_points,  points);  ... 
pclosestruct ( ) ;  ... 

popenws(ws,  conn_id,  ws_type) ;  ... 
pmsg (ws ,  msg) ;  ... 

ppoststruct (ws ,  struct_id,  priority); 
protatey (angle ,  &err_ind,  matrix);  ... 
punpoststruct (ws ,  struct_id) ;  ... 
pclosews (ws) ;  ... 
pclosephigs ( ) ;  ... 

termfp ( ) ; 
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9.36  PROTATEZ 


PROTATEZ  is  used  to  rotate  a  three  dimensional  structure 
around  the  Z-axis.  PROTATEZ  generates  the  three  dimensional 
transformation  matrix  which  will  be  used  to  perform  the  rotation. 

9.36.1  Calling  Sequence 

protatez (angle ,  &err_ind,  matrix); 

9.36.2  Parameter  Descriptions 


NAME 

I/O 

TYPE 

DESCRIPTION 

ANGLE 

INPUT 

Pf loat 

A  float  point  number  which 
specifies  the  angle  of  ro¬ 
tation,  given  in  radians 
(there  are  2  *  pi  radians 
in  a  circle) .  A  positive 
number  rotates  the  struc¬ 
ture  counter-clockwise,  a 
negative  number  rotates  it 
clockwise . 

ERR_IND 

OUTPUT 

Pint* 

, 

An  integer  which  repre¬ 
sents  an  error_code. 

MATRIX 

OUTPUT 

- - H 

Pmatrix3 

The  transformation  matrix 
which  will  be  used  to 
rotate  the  structure. 
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9.36.3  Example 

Pint  err_ind; 

Pfloat  angle  =  .5;  /*  Rotate  the  structure  by  one- 

half  of  a  radian  (about  29 
degrees)  */ 

Pmatrix3  matrix;  /*  The  transformation  matrix  */ 

Pinterstyle  style  =  1;  /*  Interior  is  hollow  */ 

Pint  num_points  =  8 ; 

Ppoint3  points []  =  {  {  0,  0,  0  }, 

<  1,  0,  0  ), 

{  1,  1,  o  ), 

{  o,  1,  0  }; 

{  0,  0,  1  }, 

{  1,  0,  1  }, 

{  1,  1,  1  }, 

(0,1,1)};  /*  A  cube  */ 

Pchar  error_f ile[ ]  =  "filename"; 

Pchar  msg[]  =  "Your  message  here!"; 

Plong  buf  size  =  512; 

Pint  structid  =  1; 

Pint  ws  =  1  ; 

Pconnid  conn  id  =  "wl.fl.w2"; 

Pfloat  priority  =  1; 

Pwstype  ws_type  =  "wl.fl.w2";  ... 

initfp ( ) ;  ... 

popenphigs (error_f ile,  buf_size) ;  ... 
popenstruct (structid) ;  ... 
psetintstyle ( style) ;  ... 
pf illarea (num_points,  points);  ... 
pclosestruct ( ) ;  ... 
popenws(ws,  conn_id,  ws_type) ;  ... 
pmsg (ws ,  msg) ;  . . . 

ppoststruct (ws,  struct_id ,  priority);  ... 
protatez (angle ,  &err_ind,  matrix);  ... 
punpoststruct (ws ,  struct_id) ;  ... 
pclosews(ws) ;  ... 
pclosephigs ( ) ;  ... 
termfp ( ) ; 
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9.37  PROTATE 


PROTATE  is  used  to  rotate  a  two  dimensional  structure  around 
the  origin  of  the  axes.  PROTATE  generates  the  two  dimensional 
transformation  matrix  which  will  be  used  to  perform  the  rotation. 

9.37.1  Calling  Sequence 

protate (angle ,  &err_ind,  matrix); 

9.37.2  Parameter  Descriptions 

NAME  I/O  TYPE  DESCRIPTION 

+ - + - + - + - + 


ANGLE 

INPUT 

Pf loat 

1 

i 

A  float  point  number  which 
specifies  the  angle  of  ro¬ 
tation,  given  in  radians 
(there  are  2  *  pi  radians 
in  a  circle) .  A  positive 
number  rotates  the  struc¬ 
ture  counter-clockwise,  a 
negative  number  rotates  it 
clockwise . 

ERR_IND 

OUTPUT 

Pint* 

An  integer  which  repre¬ 
sents  an  error__code. 

MATRIX 

OUTPUT 

Pmatrix3 

The  transformation  matrix 
which  will  be  used  to 
rotate  the  structure. 

+ - 4- - + - + - + 
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9.37.3  Example 

Pint  err_ind; 

Pfloat  angle  =  .5;  /*  Rotate  the  structure  by  one- 

half  of  a  radian  (about  29 
degrees)  */ 

Pmatrix  matrix;  /*  The  transformation  matrix  */ 

Pinterstyle  style  =1;  /*  Interior  is  hollow  */ 

Pint  num_points  =  4 ; 

Ppoint  points []  =  {  {  0,  0  }, 

(  l,  0  ), 

{  1,  1  ), 

{  0,  1  )  ;  /*  A  square  */ 

Pchar  error_file[]  =  "filename"; 

Pchar  msg[]  =  "Your  message  here!"; 

Plong  buf_size  =  512; 

Pint  structid  =  1; 

Pint  ws  =  1; 

Pconnid  conn^id  =  "wl.fl.w2"; 

Pfloat  priority  =  1; 

Pwstype  ws_type  =  "wl.fl.w2";  ... 

initfp ( ) ;  ... 

popenphigs (error_f ile,  bufsize) ;  ... 

popenstruct (structid) ;  ... 

psetintstyle (style) ;  ... 

pf illarea(num_points,  points);  ... 

pclosestruct ( ) ;  ... 

popenws (ws ,  conn_id,  wstype) ;  ... 

pmsg ( ws ,  msg )  ;  ... 

ppoststruct (ws ,  struct_id,  priority);  ... 
protate (angle,  &err_ind,  matrix);  ... 
punpoststruct (ws ,  struct_id) ;  ... 
pclosews (ws) ;  . . . 
pclosephigs ( )  ;  ... 
termfp ( ) ; 
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9.38  PCOMPOSEMATRI X 3 

PCOMPOSEMATRI X3  is  used  to  multiply  three  dimensional 
matrices  together  in  order  to  combine  transformations.  In  this 
manner  it  is  possible  to  save  both  memory  and  CPU  time. 

The  memory  is  saved  when  multiple  matrices  are  composed 
together  into  one  matrix,  eliminating  the  need  for  multiple 
matrices.  For  example,  PROTATEX  produces  Matrix  X,  PROTATEY 
produces  Matrix  Y.  X  and  Y  can  then  be  composed  back  into  the 
area  reserved  for  Matrix  X.  PROTATEZ  then  produces  its 
transformation  matrix  into  the  area  that  held  Matrix  Y.  The  new 
Matrix  Y  is  then  composed  with  the  combined  Matrix  Y  back  into 
Matrix  X. 

The  CPU  time  is  saved  when  one  transformation  is  now 
performed  on  the  composed  Matrix  X,  instead  of  a  transformation  on 
X,  then  one  on  Y,  and  then  one  on  Z. 

9.38.1  Calling  Sequence 

pcomposematrix3 (mat_x,  mat_y,  &err_ind,  result  matrix) ; 

9.38.2  Parameter  Descriptions 

NAME  I/O  TYPE  DESCRIPTION 


+ - + - + - h 


MATRIX  A 

INPUT 

Pmatrix3 

The  first  matrix  which  is 
to  be  composed  with 
another  into  a  resulting 
new  matrix. 

MATRIX  B 

INPUT 

Pmatrix3 

The  second  matrix  which  is 
to  be  composed  with  the 
first  into  a  resulting  new 
matrix . 

ERR_IND 

OUTPUT 

Pint 

An  integer  which  represents 
an  error  code. 

RESULTING 

MATRIX 

- H 

OUTPUT 

t- - - 

Pmatrix3 

i- - 

The  result  of  the  compose. 

i_ - 
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9.38.3  Example 


Pint  err_ind; 

Pfloat  angle_x  =  .5; 


Pfloat  angley  =  .5; 


Pfloat  angle_z  =  .5; 


Pmatrix3  matrix  x 


Pmatrix3  matrix_y 

Pinterstyle  style  =  1; 
Pint  num_points  =  8; 
Ppoint3  pointsf]  = 


/*  Rotate  the  structure  by  one- 
half  of  a  radian  (about  29 
degrees)  (PROTATEX)  */ 

/*  Rotate  the  structure  by  one- 
half  of  a  radian  (about  29 
degrees)  (PROTATEY)  */ 

/*  Rotate  the  structure  by  one- 
half  of  a  radian  (about  29 

degrees)  (PROTATEZ)  */ 

/*  Transformation  matrix  for 
PROTATEX  &  final  result  of 
the  COMPOSE  */ 

/*  Transformation  matrix  for 

PROTATEY  &  PROTATEZ  */ 

/*  Interior  is  hollow  */ 

} , 


{  0, 

,  0 

,  0 

( 

1, 

0, 

0 

} 

{ 

1 , 

1, 

0 

) 

{ 

0, 

1, 

0 

> 

{ 

0, 

0. 

1 

} 

( 

1, 

0, 

1 

} 

{ 

1, 

1, 

1 

> 

{ 

0, 

1, 

1 

) 

-  l  J 

Pchar  msg [ ]  =  "Your  me 
Plong  bufsize  =  512; 
Pint  structid  =  1; 
Pint  ws  =  1; 

Pconnid  conn^id  =  "wl. 
Pfloat  priority  =  1; 
Pwstype  wstype  =  "wl. 


filename" ; 
ssage  here!"? 


f  1  .w2"  ; 
f 1 . W2 "  ;  ... 


/’ 


A  cube 


initfp ( )  ?  ... 

popenphigs (error  f ile,  buf  size)  ;  ... 
popenstruct (struct_id) ;  ... 
psetintstyle (style) ;  ... 
pf illarea (num_points ,  points);  ... 
pclosestruct ( )  ;  ... 
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popenws(ws,  conn_id,  ws_type) ;  ... 
pmsg (ws,  msg) ;  ... 

ppoststruct (ws ,  struct_id,  priority);  ... 
protatex(angle_x,  &err_ind,  matrix_x) ;  ... 
protatey (angle_y ,  &err_ind,  matrix_y) ;  ... 
pcomposematrix3 (matrix_x,  matrix_y,  &err_ind, 

matrix_x) ;  ... 

protatez (angle_z ,  &err_ind,  matrix_y) ;  ... 
pcomposematrix3 (matrix_x,  matrix_y#  &err_ind, 

matrix_x) ;  ... 

punpoststruct (ws ,  struct_id) ;  ... 
pclosews (ws) ;  ... 
pclosephigs ( ) ;  ... 
termfp ( ) ; 
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9.39  PCOMPOSEMATRI X 


PCOMPOSEMATRIX  is  used  to  multiply  two  dimensional  matrices 
together  in  order  to  combine  transformations.  In  this  manner  it 
is  possible  to  save  both  memory  and  CPU  time. 

The  memory  is  saved  when  multiple  matrices  are  composed 
together  into  1  matrix,  eliminating  the  need  for  multiple 
matrices.  For  example,  PTRANSLATE  produces  Matrix  A  for  moving 
the  structure,  PSCALE  produces  Matrix  B,  for  resizing  the 
structure.  A  and  B  can  then  be  composed  back  into  the  area 
reserved  for  Matrix  A.  PROTATE  then  produces  its  transformation 
matrix  for  rotating  the  structure  back  into  the  area  that  held 
Matrix  B,  the  area  that  held  the  matrix  resizing.  The  new  Matrix 
B  is  then  composed  with  the  combined  Matrix  A  back  into  Matrix  A. 
The  CPU  time  is  then  saved  when  one  transformation  is  then  all 
that  is  required  to  perform  the  move,  the  resize,  and  the 
rotation,  instead  of  a  transformation  for  each. 


9.39.1  Calling  Sequence 


pcomposematrix (mata ,  mat_b ,  &err_ind,  result_matr ix) ; 


RESULTING  OUTPUT  Pmatrix3  The  result  of  the  compose. 
MATRIX 

+ - + - + - + - + 
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9-39.3  Example 


Pint  err_ind; 

Pvector  trans_vector 

Pvector  scale_vector 
Pfloat  angle  =  .5? 
Pmatrix  matrix  a; 


(  5, 


{  5, 


/* 


/* 


5  } ;  /*  Move  the  structure 

5  units  to  the  right 
on  the  X-axis,  5 
units  up  vertically 
on  the  Y-axis  */ 

5  }  ;  /*  Grow  the  structure  by 

a  factor  of  5  in  all 
directions  */ 

Rotate  the  structure  by  one- 
half  of  a  radian  (about  29 
degrees)  */ 

Transformation  matrix  for 
PTRANSLATE  &  final  result  of 


Pmatrix  matrixb; 

Pinterstyle  style  =  1; 
Pint  num  points  =  8 ; 
Ppoint3  points []  =  {  { 

{ 


the  COMPOSE 

/*  Transformation  matrix 
PSCALE  and  PROTATE 
/*  Interior  is  hollow 


for 


{ 


0, 

1, 

1, 

0, 

0, 

1, 

1, 

0, 


0,  0 


0, 

1, 

1, 

0, 

0, 

1, 

1, 


0 

0 

0 

1 

1 

1 

1 


} , 
}, 


) , 

>  ) 


A  cube 


Pchar  error_file[]  =  "filename" 
Pchar  msg[]  =  "Your  message  here! " ; 
Plong  bufsize  =  512; 

Pint  struct_id  =  1; 

Pint  ws  =  1 ; 

Pconnid  conn^id  =  "wl.fl.w2"; 

Pfloat  priority  =  1; 

Pwstype  ws_type  =  "wl.fl.w2";  ... 


V 

*/ 

V 


initfp ( ) ;  ... 

popenphigs(error_file,  buf_size) ;  ... 

popenstruct (struct_id) ;  ... 

psetintstyle ( sty le)  ;  ... 
pf il larea ( num_points ,  points);  ... 
pclosestruct ( ) ;  ... 
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popenws(ws,  conn_id,  ws_type) ;  ... 

pmsg(ws,  msg) ;  ... 

ppoststruct (ws ,  struct_id,  priority) ;  ... 

ptranslate ( trans_vector ,  &err_ind,  matrix_a) ;  ... 
pscale(trans  vector,  &err_ind,  matrix_b) ;  ... 
pcomposematrTx (matrix_a ,  matrix_b,  &err_ind,  matrix_  a)  ;  ... 
protate (angle,  &err^ind,  matrix_b) ;  ... 

pcomposematrix (matrlx_a ,  matrix_b,  &err_ind,  matrix_a) ;  ... 

punpoststruct (ws ,  struct_id) ;  ... 

pclosews(ws) ;  ... 

pclosephigs ( ) ;  ... 

termfp ( ) ? 
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9.40  PTRANPT3 


PTRANPT3  is  used  to  transform  a  three  dimensional  point, 
using  a  transformation  matrix  which  has  already  been  created. 

This  routine  is  used  in  order  to  forego  the  use  of  the  automatic 
PHIGS  routines  which  perform  the  transformations  for  you.  If  this 
routine  is  used  to  transform  a  polyline  which  is  defined  with  15 
points,  each  of  the  15  points  must  be  transformed  individually. 

9.40.1  Calling  Sequence 

ptranpt3  (  in__pt ,  matrix,  &err_ind,  out_pt)  ; 

9.40.2  Parameter  Descriptions 
NAME 

+ - + - + - + - + 


IN_PT 

INPUT 

Ppoint3 

The  coordinates  of  the  point 
to  be  transformed. 

MATRIX 

INPUT 

Pmatr ix3 

The  transformation  matrix  to 
be  used. 

ERR_IND 

OUTPUT 

Pint 

An  integer  which  represents 
an  error  code. 

OUT_PT 

1  OUTPUT 

1  Ppoint3 

|  The  coordinates  of  the  point 

resulting  from  the  trans¬ 
formation  . 


4 - 4- - + - 4 - 4 
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Pint  err_ind,  struct_id  =  1,  num_points  =8,  ws  =  1,  i; 
Pfloat  priority  -  1; 

Pvector3  trans_vector  =  {  5,  5,  5  }; 

Plong  buf_size  =  512; 

Pconnid  conn_id  =  "wl.fl.w2"; 

Pwstype  wstyp  =  "wl.fl.w2"; 

Pmatrix3  matrix_a; 

Pchar  error_file[]  =  "filename"; 

Ppoint3  points [ ]  =  {  {  0,  0,  0  }, 

<  1,  0,  0  }, 

{  1,  1,  0  }, 

{  0,  1,  0  }, 

{  0,  0,  1  }  , 

{  1,  o,  1  }, 

{  1,  1,  1  }, 

{0,1,1}};  /*  A  cube  */ 

initfp ( ) ;  ... 

popenphigs (error_f ile,  buf  size)  ;  ... 
popenstruct ( struct  id)  ;  ... 

ptranslate3 ( trans_vector ,  &err_ind,  matrixa); 
for  (i  =  0;  i  <  num^points;,  i++) 

ptranpt3 (points [I] ,  matrix_a,  &err  ind,  points[ij); 
ppolyl ine3 ( num_points ,  points);  ... 
pclosestruct ( ) ;  ... 
popenws(ws,  conn_id,  wstyp);  ... 
ppoststruct (ws ,  structid,  priority);  ... 
punpoststruct (ws ,  structid) ;  ... 
pclosews (ws);  ... 
pclosephigs ( )  ;  ... 

termfp ( ) ; 
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9.41  PTRANPT 


PTRANPT  is  used  to  transform  a  two  dimensional  point,  using  a 
transformation  matrix  which  has  already  been  created.  This 
routine  is  used  in  order  to  forego  the  use  of  the  automatic  PHIGS 
routines  which  perform  the  transformations  for  you.  If  this 
routine  is  used  to  transform  a  polyline  which  is  defined  with  15 
points,  each  of  the  15  points  must  be  transformed  individually. 


9.41.1  Calling  Sequence 


ptranpt  ( in_pt ,  matrix,  &err_ind,  out__pt)  ; 


9.41.2  Parameter  Descriptions 


NAME 

+ - + - + - + 


IN_PT 

INPUT 

Ppoint 3 

The  coordinates  of  the  point 
to  be  transformed. 

MATRIX 

INPUT 

Pmatrix3 

The  transformation  matrix  to 
be  used. 

ERR_IND 

OUTPUT 

Pint 

An  integer  which  represents 
an  error  code. 

0UT_PT 

!  OUTPUT 

Ppoint3 

The  coordinates  of  the  point 

resulting  from  the  trans¬ 
formation  . 


H - 1 - 1 - i - (- 


9.41.3  Example 


Pint  err_ind,  struct_id  =  1,  num_points  =  4 ,  ws 
Pfloat  priority  =  1; 

Plong  buf_size  =  512; 

Pvector  trans  vector  =  {  5,  5  }; 

Pconnid  conn_Td  =  "wl.fl.w2"; 

Pwstype  wstyp  =  "wl.fl.w2"; 

Pmatrix  rnatrix_a; 

Pchar  error_file[]  =  "filename"; 

Ppoint  points []  =  (  {  0,  0  }, 

{1,0}, 

{  1,  1  ), 

{0,1}};  /*  A  square 


=  1, 


V 


9  -  7  1 


UM  620344200 
30  September  1990 


PTRANPT 


initfp ( ) ;  ... 

popenphigs (error_f ile,  buf_size) ;  ... 
popenstruct (struct_id) ;  ... 

ptranslate ( trans_vector ,  kerr^ind,  matrix_a) ; 
for  (i  =  0;  i  <  num_points;,  T++) 

ptranpt (points [ i ] ,  matrix_a,  &err_ind,  points[i]); 
ppolyline (num_points,  points);  ... 
pclosestruct ( ) ;  ... 

popenws(ws;  conn_id,  wstyp) ;  ... 
ppoststruct (ws ,  struct_id,  priority);  ... 
punpoststruct (ws ,  struct_id) ;  ... 
pclosews(ws) ;  . . . 
pclosephigs ( ) ;  ... 

termfp ( ) ; 
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9.42  PBUI LDTRAN 3 

PBUILDTRAN3  is  used  to  build  one  three  dimensional 
transformation  matrix  for  a  series  of  transformations,  rather  than 
just  one  at  a  time.  These  transformations  include  rotating, 
scaling,  and  translating  (moving)  the  structure. 

9.42.1  Calling  Sequence 

pbuildtran3 (pt ,  shift,  x^angle,  y_angle,  z  angle,  scale, 
err_ind,  matrix) ; 

9.42.2  Parameter  Descriptions 

NAME  I/O  TYPE  DESCRIPTION 


- H 

PT 

h - - 

INPUT 

h - - 

Ppoint3 

1- - 1 

The  reference  point  around 
which  rotations  will  be  made 
to  which  the  scaling  will  be 
done . 

SHIFT 

INPUT 

Pvector3 

The  vector  along  which  the  j 
structure  is  to  be  moved. 

It  is  given  in  3-D  coord¬ 
inates.  1 

X  ANGLE 

Y  ANGLE 
Z_ANGLE 

- 1 

INPUT 

b - 

Pf loat 

b - H 

Float  point  numbers  which 
specify  the  angle  of  rota¬ 
tion,  given  in  radians 
(there  are  2  *  pi  radians 
in  a  circle) .  A  positive 
number  rotates  the  structure 
counter-clockwise,  and  a 
negative  number  rotates  it 
clockwise . 

b - +. 
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+ - H 

SCALE 

- H 

INPUT 

- -) 

Pvector3 

The  vector  along  which  the 
structure  is  to  be  resized. 
Scale  is  specified  as  an 
array  of  X-Y-Z  coordinates. 

ERR_IND 

OUTPUT 

Pint 

An  integer  which  represents 
an  error  code. 

MATRIX 

+ - H 

OUTPUT  | 

h - H 

Pmatrix3 

1 - H 

The  transformation  matrix 
which  is  generated. 

h - + 

9.42.3  Example 


Pint  err_ind,  struct  id  =  1,  num_points  =8,  ws  =  1 ,  i; 
Pfloat  x_angle  =  .5,  y_angle  =  .25,  z_angle  =  0.; 

Pfloat  priority  =  1; 

Pvector3  scale  =  {  10,  10,  10  }; 

Pvector3  trans_vector  =  {  5,  5,  5  }; 

Plong  buf_size  =  512; 

Pconnid  conn_id  =  "wl.fl.w2"; 

Pwstype  wstyp  =  "wl.fl.w2"; 

Pmatrix3  matrix_a; 

Pchar  error_file[]  =  "filename"; 

Ppoint3  points[]  =  {  {  0,  0,  0  }, 

{  1,  0,  0  }, 

{  1,  1,  0  }  , 

{  0,  1,  0  }, 

(  0,  0,  1  }, 

t  1,  o,  1  }, 

{1,1,1}, 

{0,1,1}};  /*  A  cube  */ 
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initfp ( ) ;  ... 

popenphigs (error_f ile,  buf_size) ;  ... 
popenstruct ( struct_id) ;  ... 

pbuildtran3 (points [ 0 ] ,  trans_vector ,  x_angle, 
z  angle,  scale,  &err_ind,  matrix_a 
for  (i  =  0;  T  <  num  points;,  i++) 

ptranpt3 (points [1] ,  matrix_a,  &err_ind,  po 
ppolyline3 (num_points,  points);  ... 
pclosestruct ( )  ;  ... 
popenws(ws,  conn_id,  wstyp) ;  ... 
ppoststruct (ws ,  struct_id,  priority);  ... 
punpoststruct (ws ,  struct_id) ;  ... 
pclosews (ws) ;  ... 
pclosephigs ( )  ;  ... 
termfp ( ) ; 


PBUILDTRAN3 


y_angle , 
Lnts [ i ] )  ; 
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9.43  PBUI LDTRAN 

PBUILDTRAN  is  used  to  build  one  two  dimensional 
transformation  matrix  for  a  series  of  transformations,  rather  than 
just  one  at  a  time.  These  transformations  include  rotating, 
scaling,  and  translating  (moving)  the  structure. 

9.43.1  Calling  Sequence 

pbuildtran (pt ,  shift,  angle,  scale,  &err_ind,  matrix); 

9.43.2  Parameter  Descriptions 


NAME  I/O  TYPE  DESCRIPTION 

PT 

INPUT 

Ppoint 

The  reference  point  around 
which  rotations  will  be  made 
to  which  the  scaling  will  be 
done . 

SHIFT 

INPUT 

Pvector 

i 

The  vector  along  which  the 
structure  is  to  be  moved. 

It  is  given  in  2-D  coord¬ 
inates  . 

ANGLE 

INPUT 

Pf loat 

A  float  point  number  which 
specifies  the  angle  of  ro¬ 
tation,  given  in  radians 
(there  are  2  *  pi  radians 
in  a  circle) .  A  positive 
number  rotates  the  structure 
counter-clockwise,  and  a 
negative  number  rotates  it 
clockwise . 

SCALE 

INPUT 

Pvector 

The  vector  along  which  the 
structure  is  to  be  resized. 
Scale  is  specified  as  an 
array  of  X-Y  coordinates. 

ERR_IND 

OUTPUT 

Pint 

An  integer  which  represents 
an  error  code. 

MATRIX 

OUTPUT 

h - 

Pmatr ix 

v - 

The  transformation  matrix 
which  is  generated. 
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9.43.3  Example 

Pint  err_ind,  struct_id  =  1,  num_points  =  4,  ws  =  1 ,  i; 
Pfloat  x_angle  =  .5,  y_angle  =  .25; 

Pfloat  priority  =  1; 

Pvector  scale  =  {  10,  10  )  ; 

Pvector  transjvector  =  {  5,  5  }; 

Plong  buf_si2e  =  512; 

Pconnid  conn_id  =  "wl.fl.w21'; 

Pwstype  wstyp  =  "wl.fl.w2"; 

Pmatrix  matrix_a; 

Pchar  error_file[]  =  "filename"; 

Ppoint  points []  =  {  {0,0), 

{  1/  0  }, 

{  1,  1  >, 

{0,1}};  /*  A  square  */ 

initfp ( ) ;  ... 

popenphigs (error_f ile,  buf_size) ;  ... 
popenstruct (struct_id) ;  ... 

pbuildtran (points [ 0 ] ,  trans_vector,  x_angle,  y_angle, 
scale,  &err_ind,  matrix_a) ; 
for  (i  =  0;  i  <  numpoints;,  i++) 

ptranpt (points [ i ] ,  matrix_a,  &err_ind,  pcints[i]); 
ppolyl ine ( num_points ,  points);  ... 
pclosestruct ( )  ;  ... 
popenws(ws,  conn_id,  wstyp);  ... 
ppoststruct (ws ,  struct_id,  priority);  ... 
punpoststruct ( ws ,  structid) ;  ... 
pclosews (ws) ;  ... 
pclosephigs ( ) ;  ... 
termfp ( ) ; 
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9.44  PCOMPOSETRAN 3 

PCOMPOSETRAN3  is  used  to  build  one  three  dimensional 
transformation  matrix  for  a  series  of  transformations,  and  compose 
that  matrix  together  with  the  specified  matrix.  These 
transformations  include  rotating,  scaling,  and  translating 
(moving)  the  structure. 

9.44.1  Calling  Sequence 

pcomposetran3 (matrix_a ,  pt,  shift,  x_angle,  y_angle, 
z_angle,  scale,  &err_ind,  matrixb) ; 


9.44.2  Parameter  Descriptions 
NAME  I/O  TYPE 


DESCRIPTION 


-  +  - 


MATRIX_A 

INPUT 

Pmatrix3 

The  initial  matrix  with 
which  to  compose  the  trans¬ 
formations  specified. 

PT 

INPUT 

Ppoint 3 

The  reference  point  around 
which  rotations  will  be  made 
to  which  the  scaling  will  be 
done . 

+ - 1 

SHIFT 

h - H 

INPUT 

k - H 

Pvector3 

The  vector  along  which  the 
structure  is  to  be  moved. 

It  is  given  in  3-D  coord¬ 
inates. 

X  ANGLE 

Y  Ai.GLE 
Z_ANGLE 

+ - -i 

INPUT 

L - 

Pf loat 

i- - j 

Float  point  numb' rs  which 
specify  the  angl .  of  rota¬ 
tion,  given  in  radians 
(there  are  2  *  pi  radians 
in  a  circle) .  A  positive 
number  rotates  the  structure 
counter-clockwise,  and  a 
negative  number  rotates  it 
clockw'ise. 

h - + 
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SCALE 

INPUT 

1  Pvector3 

The  vector  along  which  the 
structure  is  to  be  resized. 
Scale  is  specifieu  as  an 
array  of  X-Y-Z  coordinates. 

ERR_IND 

OUTPUT 

Pint 

An  integer  which  represents 
an  error  code. 

MATRIX_B 

+ - H 

j  OUTPUT 

Pmatrix3 

L - H 

The  transformation  matrix 
which  is  generated. 

V - + 

9.44.3  Example 

Pint  err_ind,  struct_id  =  1,  num_points  =  8 ,  ws  =  1 ,  i; 


Pfloat  x_angle  =  .5,  y_angle  = 
Pfloat  priority  =  1; 

Pvector3  scale  =  {  10,  10,  10 
Pvector3  trans_vector  =  {  5,  5 

Plong  bufsize  =  512; 

Pconnid  conn_id  =  "wl.fl.w2" ; 
Pwstype  wstyp  =  "wl.fl.w2"; 
Pmatrix3  matrix_a; 

Pchar  error_file[]  =  "filename1 
Ppoint3  points[]  =  {  j  0,  0,  0 


25 ,  z_angle  =  0 . ; 


—  If 

filename" 

t 

(  < 

0, 

0, 

0 

) , 

{ 

1, 

0, 

0 

> , 

( 

1, 

1, 

0 

} , 

i 

0, 

1, 

0 

} , 

( 

0, 

0, 

1 

) , 

< 

1, 

0, 

1 

> , 

{ 

1, 

1, 

1 

) , 

{ 

0, 

1, 

1 

} 

A  cube 
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initfp ( ) i  ;  ... 

popenphigs (error_f ile,  buf_size)  ;  ... 
popenstruct (struct_id) ;  ... 

ptranslate3 (trans_vector ,  &err_ind,  matrix_a) ; 
pcomposetran3 (matrix_a ,  points[0],  trans_vector ,  x_angle, 
y_angle,  z_angle,  scale,  &err_ind,  matrix_a) ; 
for  (i  =  0;  i  <  num^points;,  i++) 

ptranpt3 (points [T] ,  matrix_a,  &err_ind,  points[i]); 
ppolyline3  (num_points,  points)  ,*  ... 
pclosestruct ( ) ;  ... 

popenws(ws,  conn_id,  wstyp) ;  ... 
ppoststruct (ws ,  struct_id,  priority);  ... 
punpoststruct (ws ,  struct_id) ;  ... 
pclosews(ws) ;  ... 
pclosephigs ( ) ;  ... 

termfp ( ) ; 
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9.45  PCOMPOSETRAN 

PCOMPOSETRAN  is  used  to  build  one  two  dimensional 
transformation  matrix  for  a  series  of  transformations  and  compose 
it  together  with  a  specified  matrix.  These  transformations 
include  rotating,  scaling,  and  translating  (moving)  the  structure. 

9.45.1  Calling  Sequence 

pcomposetran (matrix_a ,  pt ,  shift,  angle,  scale,  &err  ind, 
matrix_b) ; 

9.45.2  Parameter  Descriptions 


NAME  I/O  TYPE  DESCRIPTION 

MATRIX_A 

INPUT 

Pmat r ix 

The  initial  matrix  with 
which  the  specified  trans- 
for‘  atons  wil  be  composed. 

PT 

INPUT 

Ppoint 

The  reference  point  around 
which  rotations  wil]  be  made 
to  which  the  scaling  will  be 
done . 

SHIFT 

INPUT 

Pvector 

The  vector  along  which  the  j 
structure  is  to  be  moved. 

It  is  given  in  2-D  coord¬ 
inates  . 

ANGLE 

INPUT 

1  Pfloat 

A  float  point  number  which  ! 

specifies  the  angle  of  ro¬ 
tation,  given  in  radians 
(there  are  2  *  pi  radians 
in  a  circle) .  A  positive 
number  rotates  the  structure 
counter-clockwise,  and  a 
negative  number  rotates  it  ! 
clockwise.  j 

4 - -  -  4 - f —  — - f - - 4 
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+ - + - + - - 


SCALE 

INPUT 

Pvector 

The  vector  along  which  the 
structure  is  to  be  resized. 
Scale  is  specified  as  an 
array  of  X-Y  coordinates. 

ERR_IND 

OUTPUT 

Pint 

An  integer  which  represents 
an  error  code. 

MATRIX_B 

OUTPUT 

Pmatrix 

i 

The  transformation  matrix 
which  is  generated. 

+ - + - + - + - + 

9.45.3  Example 

Pint  err_ind,  struct  id  =  1,  num_points  =  4 ,  ws  =  1 ,  i; 
Pfloat  x_angle  =  .5,  y_angle  =  .25; 

Pfloat  priority  =  1; 

Pvector  scale  =  {  10,  10  }; 

Pvector  trans_vector  =  {  5,  5  }; 

Plong  buf_size  =  512; 

Pconnid  conn_id  =  "wl.fl.w2"; 

Pwstype  wstyp  =  "wl.fl.w2"; 

Pmatrix  matrixa; 

Pchar  error_file[]  =  "filename"; 

Ppoint  points []  =  {  {  0,  0  }, 

\  1  /  0  }  , 

(  1,  1  >, 

{  0,  1  }  };  /*  A  square  */ 

i n i t  f p ( ) i  ;  ... 

popenphigs (error_f i le ,  buf_size)  ;  ... 

popenstruct ( structid) ;  ... 

ptranslate  (trans_vector ,  &err__ind,  matrix_a)  ; 
pcomposetran ( matrix_a ,  points[0],  trans_vector ,  x_angle, 
y_angle,  scale,  &err_ind,  matrix_a); 
for  (i  =  0;  i  <  num_points;,  i++) 

ptranpt (points [ i ] ,  matrix_a,  &err_ind,  points[i]); 
ppoly 1 ine (num_points ,  points);  ... 
pclosestruct ( )  ;  ... 
popenws(ws,  conn_id,  wstyp);  ... 
ppoststruct (ws ,  struct_id,  priority);  ... 
punpoststruct (ws ,  struct_id) ;  ... 
pclosews (ws) ;  . . . 
pclosephigs ( )  ;  ... 
termfp ( )  ; 


9-82 


UM  62034420U 
30  September  1990 

PSETTNTCOLOURIND 


9.46  PSETINTCOLOURIND 

PSETINTCOLOURIND  inserts  a  set  interior  color  index  element 
into  the  currently  open  structure.  During  traversal,  this  element 
will  set  the  interior  color  index  entry  in  the  traversal  state 
list  which  will  effect  all  subsequent  fill  area  primitives  until  a 
new  PSETINTCOLOURIND  is  encountered. 


9.46.1  Calling  Sequence 

pset intcolour ind ( index) ; 


9.46.2  Parameter  Descriptions 


NAME  I/O  TYPE  DESCRIPTION 

+ - + - + - + - + 

INDEX  INPUT  Pint  The  number  of  the  color  to  apply  toi 

all  subsequent  fill  areas.  ! 

Currently,  valid  colors  are:  i 

0  -  BLACK.  1  -  RED,  2  -  GREEN, 

3  -  YELLOW,  4  -  BLUE,  5  -  MAGENTA, 

6  -  CYAN,  7  -  WHITE 

^ - - +  — — —  -f- - •+■ - -  -  - - « - f 


Pint  index  =5;  /*  Interior  is  magenta  */ 

Pint  num_points  =  4; 

Ppoint  points[]  =  {  {  0,  0  ;, 

11,0}, 

(1,1), 

{0,1}};  /*  A  square  */ 

Pchar  error_file[]  =  "filename"; 

Pchar  msg[]  =  "Your  message  here!"; 

Plong  buf_size  =  512; 

Pint  struct_id  =  1; 

Pint  ws  =  1; 

Pconnid  conn  id  =  "wl.fl.w2"; 

Pfloat  priority  =  1; 

Pwstype  ws_type  =  "wl.fl.w2";  ... 
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initf p ( ) i  ;  ... 

popenphigs (error_f i le ,  buf_size) ;  ... 

popenstruct (struct_id)  ;  ... 

psetintcolourind ( index)  ;  ... 

pf il larea ( num_points ,  points);  ... 

pclosestruct ( )  ;  ... 

popenws ( ws ,  conn_id,  wstype) ;  ... 

pmsg (ws,  msg) ;  ... 

ppoststruct (ws,  struct_ id ,  priority);  ... 
punpoststruct (ws ,  struct^ id) ;  ... 
pclosews (ws) ;  . . . 
pclosephigs ( )  ;  ... 
termfp ( ) ; 
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9.47  PSETLOCALTRAN  3 

PSETLOCALTRAN3  inserts  a  three  dimensional  set  local 
transformation  element  into  the  currently  open  structure.  During 
traversal,  this  element  will  modify  the  local  transformation  entry 
in  the  traversal  state  list  by  composing  the  specified 
transformation  with  the  current  entry  in  the  specified  manner, 
which  will  effect  all  subsequent  primitives,  until  a  new 
PSETL0CALTRAN3  is  encountered. 


9.47.1  Calling  Sequence 
psetlocaltran3 (matrix ,  comp_type) ; 

9.47.2  Parameter  Descriptions 


NAME  I/O  TYPE  DESCRIPTION 


-+■ 


MATRIX 


INPUT 


Pmatr ix3 


The  transformation  matrix 
to  use  when  the  transfor¬ 
mation  is  performed. 


COMP  TYPE 


INPUT 


+ 


+ 


Pcomptype 


The  type  of  compose  to 
perform.  Valid  comptypes  j 
are :  j 

0  -  PREPLACE  -  replace  the  ! 
local  transformation  j 
matrix  currently  in 
place  with  the  speci¬ 
fied  matrix. 

1  -  PP0STC0N CATENATE  -  ; 

Perform  the  local  j 

transformation  currently! 
in  place,  then  perform  j 
the  transformation 
specified  'with  the  new 
matrix.  j 


j 2  -  PPRECON CATENATE  -  Per-  j 

form  the  transformation  : 

specified  by  MATRIX,  j 

then  perform  the  trans-  | 

formation  that  was  j 

already  in  place. 

+ - + 


1 
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9.47.3  Exam; 


Pint  err_ind,  struct_id  =  1,  num_points  =8,  ws  =  1 ,  i; 
Pfloat  x_angle  =  .5,  y_angle  =  .25,  z_angle  =  0.; 

Pf loat  priority  =  1  ; 

Pvector3  scale  =  {  10,  10,  10  }; 

Pvector3  trans_vector  =  (  5 ,  5 ,  5  } ; 

Plong  buf_size  =  512; 

Pconnid  conn__id  =  "wl.fl.w2"; 

Pwstype  wstyp  =  "wl.fl.w2"; 

Pmatrix3  matrix_a; 

Pchar  error_file[]  =  "filename"; 

Pcomptype  comp_type  =  PREPLACE,  ctype  =  PPRECONCATENATE ; 
Ppoint3  points[]  =  (  (  0,  0,  0  }, 

{  1,  0,  0  }, 

<  1,  1,  0  |  , 

(0,1,0), 

{  0,  0,  1  }  , 

{  1,  0,  1  ), 

(0,1,1)};  /*  A  cube  */ 


initfp ( ) ;  ... 

popenphigs (error_f ile,  buf_size) ;  ... 

popenstruct (struct  id) ;  ... 

ptranslate3 ( trans_vector ,  &err_ind,  matrix _a) ; 
psetlocaltran3 (matrix_a ,  ctype); 
pf illarea3 (num_points ,  points); 

pcomposetran3 (matrix_a ,  points[0],  trans_vector ,  x_angle, 
y_angle,  z_angle,  scale,  &err_ind,  matrix_a); 
psetlocaltran3 (matrix_a ,  comp_type) ; 
ppolyline3 (num_points,  points);  ... 
pclosestruct ( ) ;  ... 

popenws(ws,  conn_id,  wstyp);  ... 
ppoststruct (ws ,  struct^ id,  priority);  ... 
punpoststruct ( ws ,  struct_id)  ;  ... 

pclosews (ws) ;  ... 
pclosephigs ( )  ;  ... 

termf p ( ) ; 
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9.48  PSETLOCALTRAN 

PSETLOCALTRAN  inserts  a  two  dimensional  set  local 
transformation  element  into  the  currently  open  structure.  During 
traversal,  this  element  will  modify  the  local  transformation  entry 
in  the  traversal  state  list  by  composing  the  specified 
transformation  with  the  current  entry  in  the  specified  manner, 
which  will  effect  all  subsequent  primitives,  until  a  new 
PSETLOCALTRAN  is  encountered. 


9.48.1  Calling  Sequence 

pset local tran (mat rix ,  comp_type) ; 


9.48.2  Parameter  Descriptions 


NAME  I/O  TYPE  DESCRIPTION 

H - + - + - + - 

MATRIX  INPUT  Pmatrix  The  transformation  matrix 

to  use  when  the  transfor¬ 
mation  is  performed. 


•4 - - 4 - —  + - — - — - t* 

C0MP_TYPE  INPUT  Pcomptype  The  type  of  compose  to  j 

perform.  Valid  comptypes  ! 

are : 

0  -  PREPLACE  -  replace  the  j 

local  transformation  I 

matrix  currently  in  , 

place  with  the  speci¬ 
fied  matrix. 

1  -  PPOSTCONC ATEN ATE  -  j 

Perform  the  local 
transformation  currently! 
in  place,  then  perform 
the  transformation 
specified  with  the  new  | 

matrix.  j 

2  -  PPRECONC ATE NATE  -  Per¬ 

form  the  transformation  i 

i  specified  by  MATRIX, 

then  perform  the  truns-  ; 

j  formation  that  was  j 

j  already  in  place.  j 

- + - + - + - -f 
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9.48.3  Example 

Pint  err_ind,  struct_id  =  1,  num_points  =  8,  ws  =  1,  i; 
Pfloat  x_angle  =  .5,  y_angle  =  .25; 

Pfloat  priority  =  1; 

Pvector  scale  =  {  10,  10  }; 

Pvector  trans_vector  =  {  5,  5  }; 

Plong  buf_size  =  512; 

Pconnid  conn_id  =  "wl . f 1 . w2 " ; 

Pwstype  wstyp  =  "wl.fl.w2"; 

Pmatrix  matrix_a; 

Pchar  error_file[]  =  "filename"; 

Pcomptype  comp_type  =  PREPLACE,  ctype  =  PPRECONCATENATE ; 
Ppoint  points []  =  {  {  0,  0  }, 

{1,0}, 

{  1,  1  >, 

{  0,  1  }  };  /*  A  square  */ 

initfp ( ) ;  ... 

popenphigs (error  f ile,  buf_size)  ;  ... 
popenstruct ( structid) ;  ... 

ptranslate ( trans_vector ,  &err_ind,  matrix_a) ; 
psetlocaltran (matrix _a ,  ctype); 
pf illarea (num_points ,  points); 

pcomposetran (matr ix_a ,  points[0],  trans_vector ,  x_angle, 
y  angle,  scale,  &err_ind,  matrix  a)  ; 
psetlocaltran (matrix_a ,  comp_type) ; 
ppolyline(num_points,  points);  ... 
pclosestruct ( )  ;  ... 
popenws(ws,  conn__id,  wstyp);  ... 
ppoststruct ( ws ,  structid,  priority);  ... 
punpoststruct ( ws ,  struct  id) ;  ... 

pclosews (ws) ;  ... 

pclosephigs ( )  ;  ... 

termfp ( ) ; 
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9.49  PSETGLOBALTRAN 3 

PSETGLOBALTRAN 3  inserts  a  three  dimensional  set  global 
transformation  element  into  the  currently  open  structure.  During 
traversal,  this  element  will  modify  the  global  transformation 
entry  in  the  traversal  state  list  by  composing  the  specified 
transformation  with  the  current  entry  in  the  specified  manner, 
which  will  effect  all  subsequent  primitives,  until  a  new 
PSETGL0BALTRAN3  is  encountered. 


9.49.1  Calling  Sequence 
psetglobal tran3 (matrix) ; 

9.49.2  Parameter  Descriptions 


NAME 


I/O 


TYPE 


DESCRIPTION 


-+■ 


MATRIX 


INPUT 


Pmatrix3 


The  transformation  matrix 
to  use  when  the  transfor¬ 
mation  is  performed. 


9.49.3  Example 


Pint  errind,  structid  =  1,  num_points  =  8 ,  ws  -  1 ,  i; 
Pfloat  priority  =  1; 

Pvector3  trans_vector  =  {  5,  5,  5  }; 

Plong  buf_size  -  512; 

Pconnid  conn  id  =  Hwl.fl.w2"; 


Pwstype  wstyp  =  "wl 
Praatrix3  matrixa; 

.  f  1 .  w2 

(f  • 

/ 

Pchar  error_file[] 

=  "filename"; 

Ppoint3  points []  = 

{  {  o, 

0,0), 

<  i, 

0,0}, 

(  l, 

1,  0  }, 

!  0, 

1,  0  } 

Ppoint 3  pts [ ]  =  {  j 

2,  2, 

2  I  , 

{ 

3,  3, 

3  J  , 

i 

A  A. 

*  /  *  t 

4  !  , 

{ 

S 

f  f 

9  !  ;  ; 
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init f p ( ) ;  ... 

popenphigs (error_f ile ,  buf_size) ;  ... 
popenstruct ( struct_id) ;  ... 

ptranslate3 ( trans  vector,  &err_ind,  matrix_a) ; 

pglobaltran3 (matrlx_a) ; 

pf illarea3 (num_points,  points); 

ppolyline3 (num_points,  pts) ;  ... 

pclosestruct ( ) ;  ... 

popenws(ws,  conn_id,  wstyp) ;  ... 

ppoststruct (ws ,  struct_id,  priority);  ... 

punpoststruct (ws,  struct_id) ;  ... 

pclosews (ws);  ... 

pclosephigs ( ) ;  ... 

termfp ( ) ; 
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9.50  PSETGLOBALTRAN 


PSETGLOBALTRAN  inserts  a  two  dimensional  set  global 
transformation  element  into  the  currently  open  structure.  During 
traversal,  this  element  will  modify  the  global  transformation 
entry  in  the  traversal  state  list  by  composing  the  specified 
transformation  with  the  current  entry  in  the  specified  manner, 
which  will  effect  all  subsequent  primitives,  until  a  new 
PSETGLOBALTRAN  is  encountered. 

9.50.1  Calling  Sequence 

psetglobaltran (matrix) ; 


9.50.2  Parameter  Descriptions 

NAME  I/O  TYPE  DESCRIPTION 


MATRIX 


INPUT 


Pmatrix 


The  transformation  matrix 
to  use  when  the  transfor¬ 
mation  is  performed. 


9.50.3  Example 


Pint  err_ind,  struct_id  =  1,  num_points  =  8 ,  ws  =  1 ,  i; 
Pfloat  priority  =  1 ; 

Pvector  trans_vector  =  {  5,  5  }; 

Plong  buf_size  =  512; 

Pconnid  conn_id  =  "wl.fl.w2"; 

Pwstype  wstyp  =  "wl.fl.w2"; 

Pmatrix  matrix  a; 


Pchar  error_file[] 

" f ilename"  ; 

Ppoint  points[]  = 

{  ! 

0, 

0  )  , 

( 

1, 

0  I, 

{ 

1, 

1  ), 

( 

0, 

1  )  );  /*  A  square 

Ppoint  pts[ ]  =  {  { 

2, 

2 

l  / 

{ 

3, 

'3 

J 

f  , 

( 

4, 

4 

1  , 

{ 

5 , 

5 

)  };  /*  A  line  */ 

9-9  i 


UM  620344200 
30  September  1990 

PSETGLOBALTRAN 


initfp ( ) ;  ... 

popenphigs (error_f ile,  buf_size) ;  ... 
popenstruct (struct_id) ;  ... 

ptranslate (trans  vector,  &err_ind,  matrix_a) ; 

pglobaltran (matrix_a) ; 

pf illarea (num_points ,  points); 

ppolyline(num_points,  pts)  ;  ... 

pclosestruct ( ) ;  ... 

popenws(ws,  conn_id,  wstyp) ;  ... 

ppoststruct (ws ,  struct_id,  priority);  ... 

punpoststruct (ws ,  struct_id) ;  ... 

pclosews (ws) ;  ... 

pclosephigs ( ) ;  ... 

termfp ( ) ; 
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9.51  PSETWSWINDOW3 

PSETWSWINDOW3  sets  the  three  dimensional  workstation  window- 
in  the  workstation  state  list,  in  normalized  projection 
coordinates.  This  routine  sets  up  the  area  of  the  picture  that  is 
actually  going  to  be  viewed  on  the  workstation. 

9.51.1  Calling  Sequence 
psetwswindow3 ( ws ,  window); 

9.51.2  Parameter  Descriptions 

NAME  I/O  TYPE  DESCRIPTION 


- H 

WS 

r - H 

INPUT 

h - H 

Pint 

An  integer  which  identifies  the 
workstation  in  which  the 
picture  is  to  be  viewed. 

WINDOW 

- H 

INPUT 

PI imit 3 

L. - 

The  coordinates  which  define 
which  part  of  the  picture  to 
display . 

NOTE:  The  coordinates  which  define  the  area  of  the  picture  to 

display  are  normalized  projection  coordinates.  They  are  real 
numbers  between  0  and  1  which  define  the  specific  area  of  the 
picture  that  is  to  be  displayed  on  the  screen. 


Consider  the  following  figure: 
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1  + - + 

+ - + 

+  -  +  I 

I 

+  -  + 

+ - + 

0  + - 1 

0  1 


Figure  A 


Viewport 


|  + - +  | 

+ - Workstation - + 


Figure  B 

In  Figure  A,  the  picture  which  is  to  be  displayed  on  the 
workstation  is  shown.  (It  should  be  noted  that  there  is  also  a 
Z-axis  in  Figure  A  which  is  not  visible) .  In  Figure  B,  the 
workstation  and  the  viewport  on  the  workstation  in  which  the 
picture  is  to  appear  is  shown.  The  fillarea  shown  in  Figure  A 
will  be  displayed  inside  of  the  viewport  in  Figure  B. 

PSETWSWINDOW3  is  used  to  determine  how  much  of  the  picture  in 
Figure  A  will  actually  be  visible  inside  of  the  viewport  in  Figure 
B.  For  example,  if  the  area  shown  in  Figure  C  below  is  displayed 
in  the  viewport  in  Figure  B,  the  result  will  be  Figure  D: 
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+ - + 


1  + - + 

+ - + 

+  -+  |  | 

,  5  +  -  -  +  -  +  -  +  -  + 

I  !  , 

+ - +  | 

o  + - ++ 

0  .5  1 

+ - Workstation - 4- 

Figure  C 

Figure  D 

The  way  in  which  the  area  shown  in  Figure  C  is  specified  is 
as  follows: 


psetwswindow3 (ws ,  window); 

where  ws  is  equal  to  the  id  number  for  the  window  the  picture  is 
to  be  displayed  in,  and  window  is  the  set  of  normalized  projection 
coordinates  which  specify  which  part  of  the  picture  to  display,  in 
this  case,  0,  .9,  0,  .5,  0,  0.  The  coordinates  specified  are,  in 

order,  the  minimum  number  on  the  X-axis  to  display,  the  maximum 
number  on  the  X-axis  to  display,  the  minimum  number  on  the  Y-axis 
to  display,  the  maximum  number  on  the  Y-axis  to  display,  the 
minimum  number  on  the  Z-axis  to  display,  and  the  maximum  number  on 
the  Z-axis  to  display. 
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9.51.3  Example 

Pint  err_ind,  struct_id  =  1,  num_points  =8,  ws  =  1 ,  i; 
Pfloat  priority  =  1; 

Pvectoi3  trans_vector  =  {  5,  5,  5  }; 

Plong  buf_size  =  512; 

Pconnid  conn_id  =  "wl . f 1 . w2" ; 

Pwstype  wstyp  =  "wl.fl.w2"; 

Pmatrix3  matrix_a; 

Pchar  error^file[]  =  "filename”; 

Ppoint3  poTntsf]  =  {  {  0,  0,  0  }, 


{ 

1,  0,  0  ), 

{ 

1,  1,  0  ), 

{ 

0 ,  1 ,  0  }  }  ; 

/*  A  square 

Plimit3 

window  =  i 

[  o.o, 

0.5,  0.0,  0.5, 

0.0,  0.5  }  ; 

Ppoint3 

pts[]  =  { 

{  2, 

2,2), 

{  3, 

3,3), 

(  4, 

4,  4  >, 

(  5, 

5,  5  }  };  /* 

A  line  */ 

initfp ( ) ;  ... 

popenphigs (error _f ile ,  buf_size) ;  ... 
popenstruct ( struct  id) ;  ... 

ptranslate3 (trans  vector,  &err_ind,  matrix_a); 

pglobaltran3 (matrix_a) ; 

pf illarea3 (num_points,  points); 

ppolyline3 (num_points,  pts) ;  ... 

pclosestruct ( ) ;  ... 

popenws(ws,  conn_id,  wstyp);  ... 

psetwindow3 (ws ,  window); 

ppoststruct (ws,  struct  id,  priority);  ... 
punpoststruct ( ws ,  struct_id) ;  ... 

pclosews (ws) ;  ... 
pclosephigs ( )  ;  ... 

termfp ( )  ; 
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9.52  PSETWSWINDOW 

PSETWSr JNDOW  sets  the  two  dimensional  workstation  window  in 
the  workstation  state  list,  in  normalized  projection  coordinates. 
This  routine  sets  up  the  area  of  the  picture  that  is  actually 
going  to  be  viewed  on  the  workstation. 

9.52.1  Calling  Sequence 
psetwswindow ( ws ,  window); 

9.52.2  Parameter  Descriptions 


NAME  I/O  TYPE  DESCRIPTION 


- 1 

WS 

b - H 

INPUT 

b - -I 

b - - 

Pint 

| - - 1 

An  integer  wn.ich  identifies  the 
workstation  in  which  the 
picture  is  to  be  viewed. 

WINDOW 

INPUT 

b - 

PI imit 

b - 

The  coordinates  which  define 
which  part  of  the  picture  tc 
display . 

NOTE;  The  coordinates  which  define  the  area  of  the  picture  to 
display  are  normalized  projection  coordinates.  They  are  real 
numbers  between  0  and  1  which  define  the  specific  area  of  the 
picture  that  is  to  be  displayed  on  the  screen. 


Consider  the  following  figure: 
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+ - + 

r+ 1 

+-+ 


+ - + 

0  + - + 

0  1 


Figure  A 


+ - 

|  + - + 


Viewport 


|  +  —  — - — - —  — h 

-i- - Workstation - 


+ 


+ 


Fj  jure  B 

In  Figure  A,  the  picture  which  is  to  be  displayed  on  the 
workstation  is  shown.  In  Figure  B,  the  workstation  and  the 
viewport  on  the  workstation  in  which  the  picture  is  to  appear  is 
shown.  The  fillarea  shown  in  Figure  A  will  be  displayed  inside  of 
the  viewport  in  Figure  B.  PSETWSWINDOW  is  used  to  determine  how 
much  of  the  picture  in  Figure  A  will  actually  be  visible  inside  of 
the  viewport  in  Figure  B.  For  example,  if  the  area  shown  in 
Figure  C  below  is  displayed  in  the  viewport  in  Figure  B,  the 
result  will  be  Figure  D: 
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,5 

0 

Figure  C 
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h - Workstation - 
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Figure  D 

The  way  in  which  the  area  shown  in  Figure  C  is  specified  is 
as  follows: 

psetwswindow (ws ,  window) ; 

where  ws  is  equal  to  the  id  number  for  the  window  in  which  to 
display  the  picture,  and  window  is  the  set  of  normalized 
projection  coordinates  which  specify  which  part  of  the  picture  to 
display,  in  this  case,  0,  .9,  0,  .5.  The  coordinates  specified 

are,  in  order,  the  minimum  number  on  the  X-axis  to  display,  the 
maximum  number  on  the  X-axis  to  display,  the  minimum  number  on  the 
Y-axis  to  display,  and  the  maximum  number  on  the  Y-axis  to 
display . 
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9.52.3  Example 

Pint  err_ind,  struct_id  =  1,  num_points  =8,  ws  =  1,  i; 
Pfloat  priority  =  1; 

Pvector  trans_vector  =  {  5,  5  }; 

Plong  buf_size  =  512; 

Pconnid  conn  id  =  "wl.fl.w2"; 


Pwstype 

wstyp  =  "wl 

.  f  1 

.  w2  "  ; 

Pmatrix 

matrix  a; 

Pchar  error  filer  1 

If 

filename 

II  . 

t 

Ppoint 

points [ ]  =  { 

{ 

0,  0  ), 

{ 

1, 

0  }, 

( 

1, 

1  }, 

{ 

0, 

i  )  >; 

/*  A 

square  */ 

Plimit 

window  =  {  0 

.0, 

o 

ID 

O 

0,  0.5 

)  ; 

Ppoint 

pts[]  =  {  { 

2, 

2  }, 

{ 

3, 

3  }, 

{ 

4, 

4  }, 

{ 

5, 

5  }  } ; 

/*  A 

line  */ 

initfp ( ) i  ;  ... 

popenphigs (error  file,  bufsize) ;  ... 
popenstruct (structid) ;  ... 

ptranslate (trans^vector ,  &err_ind,  matrix_a) ; 

pglobaltran (matrlx_a) ; 

pf illarea (numpoints,  points); 

ppolyl ine (numpoints ,  pts) ;  ... 

pc loser  ruct ( ) ;  ... 

popenwt^ws,  conn^id,  wstyp) ;  ... 

psetwindow (ws ,  window) ; 

ppoststruct (ws ,  struct_id,  priority);  ... 
punpoststruct (ws ,  struct_id) ;  ... 
pclosews(ws) ;  ... 
pclosephigs ( )  ;  ... 
termfp ( ) ; 
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9.53  PSETWSVIEWPORT3 

PSETWSVIEWPORT3  is  used  to  set  the  three  dimensional 
workstation  viewport  size  in  the  workstation  state  list.  In  order 
to  use  this  routine,  PINQDI SPLAYS PACES I ZE3  must  first  be  called  in 
order  to  determine  the  size  of  the  available  display  space.  This 
will  return  the  length  of  the  X-axis,  the  Y-axis,  and  the  Z-axis. 
The  viewport  is  then  specified  in  real  number  coordinates  from  0 
to  the  length  of  the  axis  as  returned  from  PINQDISPLAYSPACESIZE3 
for  each  axis. 

9.53.1  Calling  Sequence 
iipsetwsviewport3 (ws ,  viewport) ; 

9.53.2  Parameter  Descriptions 

NAME  I/O  TYPE  DESCRIPTION 

+ - + - + - + - + 


WS 

INPUT 

Pint 

The 

integer  that  serves  as 

the 

identifier  for  the  work- 

station  whose  viewport  is  to 

1  be 

set . 

+ - 1 - 1 - 1 - (- 

|  VIEWPORT  I  INPUT  |  Plimit3  |  The  viewport  limits.  | 

+ - + - + - + - + 
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9.53.3  Example 

Pint  err_ind,  struct_id  =  1,  num_points  =  8 ,  ws  =  1 ,  i; 
Pfloat  priority  =  1; 


Pvector3 

trans  vector  =  { 

5, 

5,  5  }; 

Plong  buf  size  =  512; 

Pconnid 

conn  id  =  " 

wl. fl. 

w2  " 

t 

Pwstype 

wstyp  =  "wl 

. f 1 . w2 

tl  • 

f 

Pmatrix3 

matrix  a; 

Pchar  error  filer] 

=  "filename"; 

Ppoint3 

points[]  = 

{  {  o, 

o, 

0  ), 

{  1, 

o, 

0  }, 

(  1, 

1, 

0  >, 

{  o, 

1, 

0  }  ) ;  /*  A  square 

Plimit3 

window  =  { 

o 

o 

o 

.5, 

0.0,  0.5,  0.0,  0.5  ) ; 

Ppoint3 

pts[]  =  {  { 

2,  2, 

2 

}  , 

{ 

3,  3, 

3 

( 

4,  4, 

4 

>  , 

{ 

5,  5, 

5 

}  } ;  /*  A  1 ine  */ 

Pdspsize3  size; 
Plimit3  limit; 


initfp ( ) ;  ... 

popenphigs (error_f ile,  buf_size) ;  ... 
popenstruct (structid) ;  ... 

ptranslate3 (trans  vector,  &err_ind,  matrixa) ; 

pglobaltran3 (matr ix_a) ; 

pf illarea3 (num_points ,  points); 

ppolyline3 (num_points ,  pts) ;  ... 

pclosestruct ( ) ;  ... 

popenws(ws,  conn_id,  wstyp) ;  ... 

psetwindow3 (ws ,  window); 

pinqdisplayspacesize3 (wstyp,  &err_ind,  &size) ; 

limit. xmin  =  limit. ymin  =  limit. zmin  =  0.0; 

limit. xmax  =  size . device . x  /  2.0; 

limit. ymax  =  size . device . y  /  2.0; 

limit. zmax  =  size . device . z  /  2.0; 

psetwsviewport3 (ws ,  limit); 

ppoststruct (ws ,  struct_id,  priority);  ... 

punpoststruct (ws ,  struct_id) ;  ... 

pclosews ( ws) ;  ... 

pclosephigs ( ) ;  ... 

termfp ( )  ; 
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9.54  PSETWSVIEWPORT 


PSETWSVIEWPORT  is  used  to  set  the  two  dimensional  workstation 
viewport  size  in  the  workstation  state  list.  In  order  to  use  this 
routine,  PINQDISPLAYSPACESIZE  must  first  be  called  in  order  to 
determine  the  size  of  the  available  display  space.  This  will 
return  the  length  of  the  X-axis  and  the  Y-axis.  Viewport  is  then 
specified  in  real  number  coordinates  from  0  to  the  length  of  the 
axis  as  returned  from  PINQDISPLAYSPACESIZE  for  each  axis. 

9.54.1  Calling  Sequence 
psetwsviewport ( ws ,  viewport); 

9.54.2  Parameter  Descriptions 

NAME  I/O  TYPE  DESCRIPTION 

+ - + - + - + - + 


WS 

INPUT 

Pint 

The  integer  that  serves  as 
the  identifier  for  the  work¬ 
station  whose  viewport  is  to 
be  set . 

VIEWPORT  |  INPUT 

PI imit 

The  viewport  limits.  | 
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9.54.3  Example 

Pint  err_ind,  struct_id  =  1,  num_points  =8,  ws  =  1 ,  i; 
Pfloat  priority  =  1; 

Pvector  trans_vector  =  (  5,  5  }; 

Plong  buf_size  =  512; 

Pconnid  conn_id  =  "wl.fl.w2"; 

Pwstype  wstyp  =  "wl.fl.w2" ; 

Pmatrix  matrixa; 

Pchar  error_file[]  =  "filename"; 

Ppoint  points []  =  {  {  0,  0  }, 

{  1,  0  }, 

{  1,  1  >, 

{  0,  1  }  }; 

Plimit  window  =  {  0.0,  0.5,  0.0,  0.5  }; 

Ppoint  pts [ ]  ={{2,2}, 

<  3,  3  }, 

{  4,  4  >, 

<5,5}}; 

Pdspsize  size; 

Plimit  limit; 

initfp( ) |  ;  ... 

popenphigs (errorf ile,  buf_size) ;  ... 
popenstruct (struct_id) ;  ... 

ptranslate (trans  vector,  &err__ind,  matrix  a)  ; 

pglobaltran(matrix_a) ; 

pf illarea (numpoints,  points); 

ppolyline(num_points,  pts);  ... 

pclosestruct ( ) ;  ... 

popenws(ws,  conn^id,  wstyp);  ... 

psetwindow (ws ,  window) ; 

pinqdisplaysize (wstyp ,  &err_ind,  size); 

limit. xmin  =  limit. ymin  =  0.0; 

limit. xmax  =  size . device . x  /  2.0; 

limit. ymax  =  size . device . y  /  2.0; 

psetwsviewport (ws ,  limit); 

ppoststruct (ws ,  struct_id,  priority);  ... 

punpoststruct (ws ,  struct_id) ;  ... 

pclosews(ws) ;  ... 

pclosephigs ( ) ;  ... 

termfp ( ) ; 
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9.55  PREDRAWALLSTRUCT 


PREDRAWALLSTRUCT  calls  OUTSCR  and  causes  all  structures  in  a 
workstation  to  be  re-drawn. 

9.55.1  Calling  Sequence 
predrawallstruct (ws ,  control_f lag) ; 

9.55.2  Parameter  Descriptions 

NAME  I/O  TYPE  DESCRIPTION 


h - 

WS 

h - H 

INPUT 

h - H 

Pint 

h - + 

The  integer  that  serves  as 
the  identifier  for  the  work¬ 
station  in  which  all  struc¬ 
tures  are  to  be  redrawn. 

CONTROL 

FLAG 

INPUT 

— 

Pcontrol 

A  flag  which  specifies  if 
the  structures  are  always  to 
be  redrawn,  or  if  they  are  to 
be  redrawn  only  if  they  have 
changed.  (This  argument  is 

currently  ignored.) 

9.55.3  Example 


Pint  err_ind,  struct_id  =  1,  num_points  =  8 ,  ws  =  1 ,  i; 
Pfloat  priority  =  1; 

Pvector3  trans_vector  =  {  5,  5,  5  }; 

Plong  buf_size  =  512; 

Pconnid  conn_id  =  "wl.fl.w2"; 

Pwstype  wstyp  =  "wl.fl.w2"; 

Pmatrix3  matrix  a; 


Pchar  error_file[] 
Ppoint3  points[]  = 


Ppoint3  pts[]  =  { 


=  "filename"; 
{  {  0,  0,  0  ) 

{  1,  0,  0  ) 

(  1,  1,  0  , 

{  o,  1,  0  } 

{2,2,2), 

{  3,  3,  3  }, 

{  4,  4,  4  }, 

I  5,  5,  5  )  >; 


Pcontrol  contrl  =  PALWAYS; 
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initfp ( ) i  ;  ... 

popenphigs ( error_f ile ,  buf_size)  ;  ... 
popenstruct (struct_id) ;  ... 

ptranslate3 ( trans  vector,  &err_ind,  matrix_a) ; 

pglobaltran3 (matrlx_a) ; 

pf illarea3 (num_points ,  points); 

ppolyline3 (num_points,  pts) ;  ... 

pclosestruct ( ) ;  ... 

popenws(ws,  conn_id,  wstyp) ;  ... 

ppoststruct (ws ,  struct_id,  priority);  ... 

predrawallstruct (ws ,  contrl); 

pclosews(ws) ;  ... 

pclosephigs ( ) ;  ... 

termfp ( ) ; 
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9 . 56  PUPDATEWS 

PUPDATEWS  is  used  to  re-draw  the  workstation, 
calls  OUTSCR. 

9.56.1  Calling  Sequence 
pupdatews (ws ,  regen_flag) ; 

9.56.2  Parameter  Descriptions 


This  routine 


NAME 


TYPE 


DESCRIPTION 


WS 

INPUT 

Pint 

S 

The  integer  that  serves  as 
the  identifier  for  the  work¬ 
station  which  is  to  be  up¬ 
dated  . 

REGEN 

FLAG 

INPUT 

Pregen 

1 

A  flag  which  specifies  under 
circumstances  the  workstation 
is  to  be  updated.  (This 

argument  is  currently 
ignored) . 

9.56.3  Example 

Pint  err_ind,  struct_id  =  1,  num_points  =  8,  ws  =  1,  i; 
Pfloat  priority  =  1; 

Pvector3  trans_vector  =  {  5,  5,  5  }; 

Plong  buf_size  =  512; 


Pmatrix3  matrix_a; 
Pchar  error_file[] 
Ppoint3  points[]  = 


Ppoint 3  pts [ ]  =  { 


=  (  5, 

5, 

5  } 

f 1.W2" 

/ 

.  w2" ; 

f i lename" 

/ 

0,  0, 

0 

}  , 

1,  0, 

0 

1  , 

1,  1, 

0 

)  , 

0,  1, 

0 

}  > ; 

2,  2 

> , 

3,  3 

) , 

4,  4 

} , 

5,  5 

}  } 

t 

A  square 


A  line 


Pregen  contrl 


PPERFORM; 
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initfp ( )  ;  ... 

popenphigs (error_f ile ,  buf_size) ;  ... 
popenstruct (struct_id) ;  ... 

ptranslate3 ( trans  vector,  &err_ind,  matrix  a); 

pglobaltran3 (matrlx_a) ; 

pf illarea3 (num_points,  points); 

ppolyline3 (num_points ,  pts) ;  ... 

pclosestruct ( ) ;  ... 

popenws(ws,  conn_id,  wstyp) ;  ... 

ppoststruct (ws ,  struct_id ,  priority);  ... 

pupdatews (ws ,  contrl) ; 

pclosews (ws) ;  . .  . 

pclosephigs ( )  ;  ... 

termfp ( ) ; 
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9.57  PINQWSTYPES 

PINQWSTY PES  returns  the  list  of  workstation  types  which  can 
be  used  as  parameters  to  POPENWS. 

9.57.1  Calling  Sequence 

pinqwstypes ( size ,  &err  ind,  buffer,  types,  &tot_size) ; 

9.57.2  Parameter  Descriptions 

NAME  I/O  TYPE  DESCRIPTION 

+ - + - + - + - + 


|  SIZE  j  INPUT  |  Pint  j  The  size  of  the  buffer.  j 

+ - f*  — 1 - — 1 - 1- 


ERR_IND 

+ - H 

|  BUFFER 

OUTPUT 

h - i 

OUTPUT  j 

Pint* 

I - H 

Pchar* 

An  integer  that  repre¬ 
sents  an  error  code. 

i- - a 

The  output  buffer.  j 

|  TYPES 

|  OUTPUT 

P'wstypelst 

|  Fixed  information. 

TOT  SIZE 

OUTPUT 

Pint* 

The  size  of  the  buffer  j 

i - 

space  actually  used.  | 

9.57.3  Example 

Pint  err_ind,  size  --  1024,  total; 

Pwstypelst  types; 

Pchar  buf fer [ size ]  ; 

Plong  buf_size  =  512; 

Pchar  error_file[]  =  "filename"; 

initfp ( ) ;  ... 

popenphigs ( error  file,  buf_size) ;  ... 

pinqwstypes (size ,  &err_ind,  buffer,  types,  &total); 
pclosephigs ( ) ;  ... 

termf p ( ) ; 
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9.58  PINQWSCONNTYPE 

PINQWSCONNTYPE  returns  the  connection  identifier  and  specific 
workstation  type  associated  with  the  specified  open  workstation. 

9.58.1  Calling  Sequence 

pinqwsconntype (ws ,  size,  &err_ind,  buffer,  conn_id, 
tot_size,  ws_type) ; 

9.58.2  Parameter  Descriptions 


NAME  I/O  TYPE  DESCRIPTION 

WS 

INPUT 

Pint 

The  workstation  identi¬ 
fier  . 

|  SIZE 

|  INPUT 

Pint  |  The  size  of  the  buffer. 

ERR_IND 

OUTPUT 

Pint* 

I 

An  integer  that  repre¬ 
sents  an  error  code. 

|  BUFFER 

|  OUTPUT  |  Pchar*  |  The  output  buffer. 

CONNID  |  OUTPUT  j  Pconnid  |  The  connection  id. 

TOT_S IZE 

OUTPUT  |  Pint* 

I 

The  size  of  the  buffer 
space  actually  used. 

|  WS_TYPE 

H - 

|  OUTPUT  |  Pwstype  |  Fixed  information. 

9.58.3  Example 

Pint  ws  =  1 ; 

Pint  errind,  size  =  1024,  total; 
Pwstypelst  types; 

Pchar  buf fer[size] ; 

Plong  buf_size; 

Pchar  error_f ile [ ]  =  "filename"; 
Pconnid  conn_id  =  "wl.fl.w2",  id; 
Pwstype  wstyp  =  "wl.fl.w2",  type; 
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initfp() ; 

popenphigs (error_f ile,  buf_size) ;  ... 

popenws(ws,  conn_id,  wstyp) ;  ... 

Pinqwsconntype (ws ,  size,  &err_ind,  buffer,  id,  &total, 
type) ; 

pclosews (ws) ;  ... 
pclosephigs ( )  ;  ... 
termfp ( ) ; 
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9 . 59  PINQDIS PLAYS PACES I ZE3 

This  routine  returns  the  three  dimensional  display  size  of 
the  specified  workstation. 

9.59.1  Calling  Sequence 

pinqdisplayspacesize3 ( type ,  &err_ind,  size); 


9.59.2  Parameter  Descriptions 


NAME  I/O  TYPE  DESCRIPTION 


TYPE 

1 

INPUT 

Pint 

1 

Workstation  type. 

ERR_IND 

OUTPUT 

1 

Pint 

1 

Error  indicator. 

SIZE 

1 

OUTPUT 

1 

Pdspsize3 

1 

Display  size. 
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9.59.3  Example 


Pint  err_ind,  struct_id  =  1,  num_points  =8,  ws  =  1 ,  i; 
Pfloat  priority  =  1; 

Pvector3  trans_vector  =  {  5,  5,  5  }; 

Plong  buf_size  =  512; 

Pconnid  conn  id  =  "wl.fl.w2"; 


Pwstype 

wstyp  =  "wl 

. f 1 . w2 "  ; 

Pmatrix3 

matrix  a; 

Pchar  error  file[] 

=  "filename 

ii 

f 

Ppoint3 

pomts[]  = 

(  {  0,  0, 

0 

} , 

{  i,  o, 

0 

)  I 

{  1,  1, 

0 

}, 

{  0,  1, 

0 

}  }; 

Plimit3 

window  =  ( 

o 

in 

o 

o 

o 

o 

o 

o 

in 

o 

o 

Ppoint3 

pts[]  =  {  { 

2,  2,  2  ), 

{ 

3,  3,  3  }, 

{ 

4,  4,  4  ), 

1 

5,  5,  5  } 

} 

;  /*  A  line 

Pdspsize3  size; 


initfp ( ) ;  ... 

popenphigs (error_f ile,  buf_size) ;  ... 

popenstruct (struct_id) ;  ... 

ptranslate3 (trans^vector ,  &err_ind,  matrix  a) ; 

pglobaltran3 (matrlx_a) ; 

pf illarea3 (num_points ,  points); 

ppolyline3 (num_points,  pts) ;  ... 

pclosestruct ( ) ;  ... 

popenws(ws,  conn_id,  wstyp) ;  ... 

psetwindow3 (ws ,  window); 

pinqdisplayspacesize3 (wstyp,  &err_ind,  &size) ; 

ppoststruct (ws ,  struct_id,  priority);  ... 

punpoststruct (ws ,  struct_id) ;  ... 

pclosews (ws) ;  ... 

pclosephigs ( ) ;  ... 

termfp ( ) ; 
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9.60  PI NQDI SPLAYS PACES  I ZE 

This  routine  returns  the  two  dimensional  display  size  of  the 
specified  workstation. 

9.60.1  Calling  Sequence 
pinqdisplayspacesize ( type ,  err_ind,  size); 

9.60.2  Parameter  Descriptions 

NAME  I/O  TYPE  DESCRIPTION 

4 - —  — —  — b - — - b  - 1 - - + 


TYPE 

INPUT 

Pint 

Workstation  type.  Can  be 

determined  by  calling 

PINQWSCONNTYPE. 

+ - + - + - + - + 

|  ERR__IND  |  OUTPUT  j  Pint  |  Error  indicator.  j 

■b  *“  —  — >  —  — —  — -b  “  —  —  —  — .  —  —  — -f-  —  —  — —  —  —  —  —  -b  —  —  —  -  —  —  — —  “  —  —  “  —  —  —  —  -b 

!  SIZE  |  OUTPUT  |  Pdspsize  |  Display  size.  | 

H - + - + - + - + 


9.60.3  Example 

Pint  ws  =  1; 

Pint  err_ind,  size  =  1024,  total; 

Pwstypelst  types; 

Pchar  buffer[size] ; 

Plong  buf_size  =  512; 

Pchar  error_file[]  =  "filename"; 

Pconnid  conn_id  =  "wl.fl.w2",  id; 

Pwstype  wstyp  =  "wl.fl.w2",  type ; 

initfp ( ) i  ;  ... 

popenphigs (error_f ile,  buf_size) ;  ... 

popenws(ws,  conn_id,  wstyp);  ... 

pinqwsconntype (ws ,  size,  &err_ind,  buffer,  id,  &total, 
type) ; 

pclosews (ws) ;  ... 

pclosephigs ( ) ;  ... 
termfp ( ) ; 
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9.61  PHIGS  Data  Structures 

This  section  lists  the  PHIGS  data  structures  necessary  for 
the  PHIGS  callable  routines.  These  structures  are  included  in  the 
include  file  ELEMENT. H. 


typedef 

char 

Pchar ; 

/* 

Phigs  CHARacter 

V 

typedef 

int 

Pint  ; 

/* 

Phigs  INTeger 

V 

typedef 

long 

Plong ; 

/* 

Phigs  LONG  integer 

V 

typedef 

float 

Pfloat ; 

/* 

FLOATing  point  data 

*/ 

typedef 

int 

Ptype ; 

/* 

Phigs  element  TYPE  declaration 

*/ 

typedef  struct  /*  Integer  POINT  */ 

{  . 

Pint  x;  /*  X  coordinate  */ 

Pint  y;  /*  Y  coordinate  */ 

} Pipoint ; 

typedef  struct 
l 

Pint  x;  /*  X  coordinate 

Pint  y;  /*  Y  coordinate 

Pint  z;  /*  Z  coordinate 

>  Pipoint3 ; 

typedef  enum  /*  CONTROL  parameter  (for  redraw 

structures)  */ 

{ 

PCONDITIONALLY , 

PALM AYS 
) Pcontrol ; 

typedef  struct 
( 

Pfloat  xmin; 

Pfloat  xmax; 

Pfloat  ymin; 

Pfloat  ymax; 

) PI imit ; 

typedef  struct 
{ 

Pfloat  xmin; 

Pfloat  xmax; 

Pfloat  ymin; 

Pfloat  ymax; 

Pfloat  zmin; 

Pfloat  zmax; 

) PI imit3 ; 


/*  3-d  Integer  POINT  *. 

*/ 

V 

V 
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typedef  enum 
{ 

PPERFORM, 

PPOSTPONE 
} Pregen ; 

typedef  EPATH  Pconnid;  /*  connection  identifier  */ 

typedef  EPATH  Pwstype ;  /*  Workstation  TYPE  (window  name)  */ 

typedef  struct 
{ 

Pint  number;  /*  number  of  WS  types  in  list  */ 

Pwstype  *ws_types;  /*  list  of  types  */ 

) Pwstypelst ; 

typedef  Pfloat  Pmatrix [ 3 ] [ 3 ] ;  /*  2-D  space  transformation 

matrix  */ 

typedef  Pfloat  Pmatr ix3 [ 4 ] [ 4 ] ;  /*  3-D  space  transformation 

matrix  */ 

typedef  enum  /*  matrix  COMPosition  type  */ 

( 

PPRECONCATENATE , 

PPOSTCONCATENATE , 

PREPLACE 
} Pcomptype ; 

typedef  struct  /*  2-D  point  */ 

{ 

Pfloat  x; 

Pfloat  y; 

) Ppoint ; 

typedef  struct  /*  3-D  point  */ 

{ 

Pfloat  x; 

Pfloat  y; 

Pfloat  z; 

) Ppoint 3 ; 

typedef  Ppoint  Pvector;  /*  2-D  vector  definition  */ 

typedef  Ppoint3  Pvector3 ;  /*  3-D  vector  definition  */ 

typedef  enum 
( 

PDCMETERS , 

PDC_OTHER 
}  Pdevunits ; 
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typedef  struct 

l 

Pdevunits  units; 

Ppoint3  device; 

Pipoint3  raster; 

} Pdspsize3 ; 

typedef  struct 
{ 

Pdevunits  units; 
Ppoint  device; 
Pipoint  raster; 
} Pdspsize ; 

typedef  enum  /* 

{ 

PDELETE , 

PKEEP 


units  */ 
units  */ 
units  */ 


/*  Device  coordinate 
/*  device  volume  in  coordinate 
/*  device  volume  in  raster 


units  */ 
units  */ 
units  */ 


/*  Device  coordinate 
/*  device  size  in  coordinate 
/*  device  size  in  raster 


REFerence  Flag  (delete  structure 
network)  */ 


} Pref f ; 

typedef  enum  /*  interior  style  for  fill  area  */ 

{ 

PHOLLOW, 

PSOLID, 

PPATTERN , 

PHATCH , 

PEMPTY 
}Pinterst ; 

#define  Pinterstyle  Pinterst 
/*  line  types  */ 


#def ine  PLN_SOLID  1 
#def ine  PLN_DASH  2 
#def ine  PLN_DOT  3 
#def ine  PLN  DOT DASH  4 
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/*  marker  types  */ 


tdefine  PMK_POINT  1 
#def ine  PMK_PLUS  2 
tdefine  PMK_STAR  3 
tdefine  PMK_0  4 
#def ine  PMK_X  5 

/*  available  colors  */ 

tdefine  COL_BLACK  0 
tdefine  COLJRED  1 
tdefine  COL_GREEN  2 
tdefine  COL_YELLOW  3 
tdefine  COL_BLUE  4 
tdefine  COL_MAGENTA  5 
tdefine  COL_CYAN  6 
tdefine  COL  WHITE  7 
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